package flare.util
{
/**
* Utility methods for working with arrays.
*/
public class Arrays
{
public static const EMPTY:Array = new Array(0);
/**
* Constructor, throws an error if called, as this is an abstract class.
*/
public function Arrays() {
throw new ArgumentError("This is an abstract class.");
}
/**
* Returns the maximum value in an array. Comparison is determined
* using the greater-than operator against arbitrary types.
* @param a the array
* @param p an optional property from which to extract the value.
* If this is null, the immediate contents of the array are compared.
* @return the maximum value
*/
public static function max(a:Array, p:Property=null):Number
{
var x:Number = Number.MIN_VALUE;
if (p) {
var v:Number;
for (var i:uint=0; i<a.length; ++i) {
v = p.getValue(a[i]);
if (v > x) x = v;
}
} else {
for (i=0; i<a.length; ++i) {
if (a[i] > x) x = a[i];
}
}
return x;
}
/**
* Returns the index of a maximum value in an array. Comparison is
* determined using the greater-than operator against arbitrary types.
* @param a the array
* @param p an optional property from which to extract the value.
* If this is null, the immediate contents of the array are compared.
* @return the index of a maximum value
*/
public static function maxIndex(a:Array, p:Property=null):Number
{
var x:Number = Number.MIN_VALUE;
var idx:int = -1;
if (p) {
var v:Number;
for (var i:uint=0; i<a.length; ++i) {
v = p.getValue(a[i]);
if (v > x) { x = v; idx = i; }
}
} else {
for (i=0; i<a.length; ++i) {
if (a[i] > x) { x = a[i]; idx = i; }
}
}
return idx;
}
/**
* Returns the minimum value in an array. Comparison is determined
* using the less-than operator against arbitrary types.
* @param a the array
* @param p an optional property from which to extract the value.
* If this is null, the immediate contents of the array are compared.
* @return the minimum value
*/
public static function min(a:Array, p:Property=null):Number
{
var x:Number = Number.MAX_VALUE;
if (p) {
var v:Number;
for (var i:uint=0; i<a.length; ++i) {
v = p.getValue(a[i]);
if (v < x) x = v;
}
} else {
for (i=0; i<a.length; ++i) {
if (a[i] < x) x = a[i];
}
}
return x;
}
/**
* Returns the index of a minimum value in an array. Comparison is
* determined using the less-than operator against arbitrary types.
* @param a the array
* @param p an optional property from which to extract the value.
* If this is null, the immediate contents of the array are compared.
* @return the index of a minimum value
*/
public static function minIndex(a:Array, p:Property=null):Number
{
var x:Number = Number.MAX_VALUE, idx:int = -1;
if (p) {
var v:Number;
for (var i:uint=0; i<a.length; ++i) {
v = p.getValue(a[i]);
if (v < x) { x = v; idx = i; }
}
} else {
for (i=0; i<a.length; ++i) {
if (a[i] < x) { x = a[i]; idx = i; }
}
}
return idx;
}
/**
* Fills an array with a given value.
* @param a the array
* @param o the value with which to fill the array
*/
public static function fill(a:Array, o:*) : void
{
for (var i:uint = 0; i<a.length; ++i) {
a[i] = o;
}
}
/**
* Makes a copy of an array or copies the contents of one array to
* another.
* @param a the array to copy
* @param b the array to copy values to. If null, a new array is
* created.
* @param a0 the starting index from which to copy values
* of the input array
* @param b0 the starting index at which to write value into the
* output array
* @param len the number of values to copy
* @return the target array containing the copied values
*/
public static function copy(a:Array, b:Array=null, a0:int=0, b0:int=0, len:int=-1) : Array {
len = (len < 0 ? a.length : len);
if (b==null) {
b = new Array(b0+len);
} else {
while (b.length < b0+len) b.push(null);
}
for (var i:uint = 0; i<len; ++i) {
b[b0+i] = a[a0+i];
}
return b;
}
/**
* Clears an array instance, removing all values.
* @param a the array to clear
*/
public static function clear(a:Array):void
{
while (a.length > 0) a.pop();
}
/**
* Removes an element from an array. Only the first instance of the
* value is removed.
* @param a the array
* @param o the value to remove
* @return the index location at which the removed element was found,
* negative if the value was not found.
*/
public static function remove(a:Array, o:Object) : int {
var idx:int = a.indexOf(o);
if (idx == a.length-1) {
a.pop();
} else if (idx >= 0) {
a.splice(idx, 1);
}
return idx;
}
/**
* Removes the array element at the given index.
* @param a the array
* @param idx the index at which to remove an element
* @return the removed element
*/
public static function removeAt(a:Array, idx:uint) : Object {
if (idx == a.length-1) {
return a.pop();
} else {
var x:Object = a[idx];
a.splice(idx,1);
return x;
}
}
/**
* Performs a binary search over the input array for the given key
* value, optionally using a provided property to extract from array
* items and a custom comparison function.
* @param a the array to search over
* @param key the key value to search for
* @param prop the property to retrieve from objecs in the array. If null
* (the default) the array values will be used directly.
* @param cmp an optional comparison function
* @return the index of the given key if it exists in the array,
* otherwise -1 times the index value at the insertion point that
* would be used if the key were added to the array.
*/
public static function binarySearch(a:Array, key:Object,
prop:String=null, cmp:Function=null) : int
{
var p:Property = prop ? Property.$(prop) : null;
if (cmp == null)
cmp = function(a:*,b:*):int {return a>b ? 1 : a<b ? -1 : 0;}
var x1:int = 0, x2:int = a.length, i:int = (x2>>1);
while (x1 < x2) {
var c:int = cmp(p ? p.getValue(a[i]) : a[i], key);
if (c == 0) {
return i;
} else if (c < 0) {
x1 = i + 1;
} else {
x2 = i;
}
i = x1 + ((x2 - x1)>>1);
}
return -1*(i+1);
}
/**
* Sets a named property value for items stored in an array.
* The value can take a number of forms:
* <ul>
* <li>If the value is a <code>Function</code>, it will be evaluated
* for each element and the result will be used as the property
* value for that element.</li>
* <li>If the value is an <code>IEvaluable</code> instance, it will be
* evaluated for each element and the result will be used as the
* property value for that element.</li>
* <li>In all other cases, the property value will be treated as a
* literal and assigned for all elements.</li>
* </ul>
* @param list the array to set property values for
* @param name the name of the property to set
* @param value the value of the property to set
* @param filter a filter function determining which items
* in the array should be processed
* @param p an optional <code>IValueProxy</code> for setting the values
*/
public static function setProperty(a:Array,
name:String, value:*, filter:Function, p:IValueProxy=null):void
{
if (p == null) p = Property.proxy;
var v:Function = value is Function ? value as Function :
value is IEvaluable ? IEvaluable(value).eval : null;
for each (var o:Object in a) if (filter==null || filter(o))
p.setValue(o, name, v!=null ? v(p.$(o)) : value);
}
} }