<?
/// Useful array related functions I didn't, at one time, find in php
class Arrays{
	
	/// Gets an element of an arbitrarily deep array using list of keys for levels
	/**
	@param	keys array comma separated list of keys to traverse
	@param	array	array	The array which is parsed for the element
	*/
	static function toElement($keys,$array){
		if($keys){
			foreach($keys as $key){
				$array = $array[$key];
			}
		}
		return $array;
	}
	
	/// Updates an arbitrarily deep element in an array using list of keys for levels
	/** Traverses an array based on keys to some depth and then updates that element
	@param	keys array comma separated list of keys to traverse
	@param	array	array	The array which is parsed for the element
	@param	update any	the new value of the element
	*/
	static function updateElement($keys,&$array,$update){
		$tmpArray[] =& $array;
	
		if($keys){
			$i = 0;
			foreach($keys as $key){
				$tmpArray[] =& $tmpArray[$i][$key];
				$i++;
			}
		}
		$tmpArray[count($tmpArray)-1] = $update;
	}
	/// takes an array and flattens it to one level using separator to indicate key deepness 
	/**
	@param	array	a deep array to flatten
	@param	separator	the string used to indicate in the flat array a level of deepenss between key strings
	@param	keyPrefix used to prefix the key at the current level of deepness
	@return	array
	*/
	static function flatten($array,$separator='_',$keyPrefix=null){
		foreach($array as $k=>$v){
			if($fK){
				$key = $keyPrefix.$separator.$k;
			}else{
				$key = $k;
			}
			if(is_array($v)){
				$sArrays = self::arrayFlatten($v,$key,$separator);
				foreach($sArrays as $k2 => $v2){
					$sArray[$k2] = $v2;
				}
			}else{
				$sArray[$key] = $v;
			}
		}
		return $sArray;
	}
	///Takes an arary of arbitrary deepness and turns the keys into tags and values into data
	/**
	@param	array	array to be turned into xml
	@param	depth	internal use
	*/
	function toXml($array,$depth=0){
		foreach($array as $k=>$v){
			if(is_array($v)){
				$v = arrayToXml($v);
			}
			$ele[] = str_repeat("\t",$depth).'<'.$k.'>'.$v.'</'.$k.'>';
		}
		return implode("\n",$ele);
	}
	///Set the keys equal to the values or vice versa
	/**
	@param array the array to be used
	@param	type	"key" or "value".  Key sets all the values = keys, value sets all the keys = values
	@return array
	*/
	static function setEqualKeysValues($array,$type='key'){
		if($type == 'key'){
			$array = array_keys($array);
			foreach($array as $v){
				$newA[$v] = $v;
			}
		}else{
			$array = array_values($array);
			foreach($array as $v){
				$newA[$v] = $v;
			}
		}
		return $newA;
	}
	///mergers if two arrays, else returns the existing array
	static function merge($x,$y){
		if(is_array($x)){
			if(is_array($y)){
				return array_merge($x,$y);
			}else{
				return $x;
			}
		}else{
			return $y;
		}
	}
	///removes values that equate to false
	static function filterFalse(&$array){
		foreach($array as $k=>$v){
			if(!$v){
				unset($array[$k]);
			}
		}
	}
	///for an incremented key array, find first gap in key numbers, or use end of array
	static function firstAvailableKey($array){
		if(!is_array($array)){
			return 0;
		}
		$key = 0;
		ksort($array);
		foreach($array as $k=>$v){
			if($k != $key){
				return $key;
			}
			$key++;
		}
		return $key;
	}
	///remove non numbers from an array
	/**
	@param	list	either a flat array or a comman separated values
	*/
	static function filterNumberList($list){
		if(!is_array($list)){
			$list = Arrays::explode(',',$list);
		}
		$filteredList = array();
		foreach($list as $v){
			if(Tool::isInt($v)){
				$filteredList[] = $v;
			}
		}
		return $filteredList ? $filteredList : array();
	}
	///Add into an array based on key; if key doesn't exist, just add to end of array
	/**
	@param	key	can be null or key or array.  If null, value added to end of array
	@param	value	value to add to array
	@param	array	array that will be modified
	*/
	static function addOnKey($key,$value,&$array){
		if($key !== null && $key !== false){
			$array[$key] = $value;
			return $key;
		}else{
			$array[] = $value;
			return count($array) - 1;
		}
	}
	///adds to the array and overrides duplicate elements
	/**removes all instances of some value in an array then adds the value according to the key
	@param	value	the value to be removed then added
	@param	array	the array to be modified
	@param	key	the key to be used in the addition of the value to the array; if null, value added to end of array
	*/
	static function addOverride($value,&$array,$key=null){
		self::remove($value);
		self::addOnKey($key,$value,$array);
		return $array;
	}
	///removes all instances of value from an array
	/**
	@param	value	the value to be removed
	@param	array	the array to be modified
	*/
	static function remove($value,&$array){
		$existingKey = array_search($value,$array);
		while($existingKey !== false){
			unset($array[$existingKey]);
			$existingKey = array_search($value,$array);
		}
	}
	/// creates an array using some other sequential array of arrays where the value of the arrays "key" is used as a key and the value of the arrays "name" is used as the value
	/**
	@param	array	array used to make the return array
	@param	key	key to use in the sub arrays of input array to be used as the keys of the output array
	@param	name	value to be used in the output array.  If not specified, the value defaults to the rest of the array apart from the key
	@return	key to name mapped array
	*/
	function addKey($array,$key = 'id',$name=null){
		if(is_array($array)){
			foreach($array as $part){
				$keyValue = $part[$key];
				if($name){
					$newArray[$keyValue] = $part[$name];
				}else{
					unset($part[$key]);
					if(count($part) > 1 ){
						$newArray[$keyValue] = $part;
					}else{
						$newArray[$keyValue] = array_pop($part);
					}
				}
			}
			return $newArray;
		}
	}
}