Packagenet.guttershark.util
Classpublic final class ArrayUtils

The ArrayUtils class contains utility methods for arrays.

See also

Utilities class.

Public Methods
 MethodDefined by
  
asearch(array:Array, conditions:Object, options:Object = null):*
Advanced array searching with complex matching conditions.
ArrayUtils
  
asearchAll(array:Array, conditions:Object):Array
Shortcut for advanced searching by a single property.
ArrayUtils
  
asearchBy(array:Array, property:String, value:Object, options:* = null):*
Shortcut for advanced searching by a single property.
ArrayUtils
  
asearchFirst(array:Array, conditions:Object):*
Shortcut for advanced searching for the first matching item.
ArrayUtils
  
asearchLast(array:Array, conditions:Object):*
Shortcut for advanced searching for the last matching item.
ArrayUtils
  
clone(array:Array):Array
Clones an array.
ArrayUtils
  
compare(a:Array, b:Array, ordered:Boolean = false):Boolean
Compare two arrays to see if their values (and optionally order) are identical.
ArrayUtils
  
contains(a:Array, element:Object):Boolean
Determines if a value exists within the array.
ArrayUtils
  
equals(arr1:Array, arr2:Array):Boolean
Determine if one array is identical to the other array.
ArrayUtils
  
gi():ArrayUtils
[static] Singleton access.
ArrayUtils
  
insert(a:Array, element:Object, index:int):Array
Insert an element into an array at a specific index.
ArrayUtils
  
locatePropVal(a:Array, prop:String, val:Object, caseInsensitive:Boolean = false):Object
Search for a unique property/value match in an array of complex objects.
ArrayUtils
  
locatePropValIndex(a:Array, prop:String, val:Object, caseInsensitive:Boolean = false):int
Search for a unique property/value match in an array of complex objects and return its index in the array.
ArrayUtils
  
matchValues(a:Array, b:Array):Boolean
Compares two arrays to see if any two indexes have the same value as the other array.
ArrayUtils
  
maxIndex(a:Array):int
Return the array index of the maximum value in a numeric array.
ArrayUtils
  
maxVal(a:Array):Number
Return the maximum value in a numeric array.
ArrayUtils
  
merge(a:Array, b:Array):Array
Merge two arrays into one.
ArrayUtils
  
minIndex(a:Array):int
Return the array index of the minimum value in a numeric array.
ArrayUtils
  
minValue(a:Array):Number
Return the minimum value in a numeric array.
ArrayUtils
  
nearestNeighbor(val:Number, range:Array, returnIndex:Boolean = false):Number
Locate and return the (lowest) nearest neighbor or matching value in a NUMERIC sorted array of Numbers.
ArrayUtils
  
remove(a:Array, element:Object):Array
Remove all instances of an element from an array.
ArrayUtils
  
removeDuplicate(a:Array):Array
Remove duplicates from an array and return a new array.
ArrayUtils
  
shuffle(a:Array):void
Shuffle array elements.
ArrayUtils
  
sliceByPropVal(a:Array, prop:String, val:Object, caseInsensitive:Boolean = false):Array
Return a new array sliced from the original array of complex objects based on a prop/val match
ArrayUtils
  
swap(a:Array, index1:int, index2:int):Array
Swap two element's positions in an array.
ArrayUtils
  
uniqueCopy(a:Array):Array
Create a new array that contains unique instances of objects.
ArrayUtils
Method detail
asearch()method
public function asearch(array:Array, conditions:Object, options:Object = null):*

Advanced array searching with complex matching conditions.

Parameters
array:Array
 
conditions:Object
 
options:Object (default = null)

Returns
*

Example
Example uses. 
  
   var movies:Array = []; //retrieve from some datasource
   
   var at:ArrayUtils = ArrayUtils.gi();
   
   //find with simple property value condition
   var moviesByMichaelBay:Array = at.asearch(movies,{director:'Michael Bay'});
   
   //find with property chain condition (assuming the 'released' property returns a Date instance)
   var moviesByMichaelByReleasedIn2007:Array = at.asearch(moviesByMichaelBay,{'released.fullYear':2007});
   
   //find only the first object.
   var moviesByMichaelByReleasedIn2007:Array = at.asearch(moviesByMichaelBay,{'released.fullYear':2007,{find:"first"}});
   
   //find only the last object.
   var moviesByMichaelByReleasedIn2007:Array = at.asearch(moviesByMichaelBay,{'released.fullYear':2007,{find:"last"}});
   
   //find all objects that match (this is the default if no options are provided).
   var moviesByMichaelByReleasedIn2007:Array = at.asearch(moviesByMichaelBay,{'released.fullYear':2007,{find:"all"}});
   
   //find with class condition - Drama is a class., so any movies[i].genre that is of type Drama, will match and be returned.
   var moviesThatAreClass:Array = at.asearch(movies,{genre:Drama});
   
   //find with Function condition.
   var moviesWithAverageRatings:Array = at.asearch(movies,{rating:function(item:Movie,actual:Number):Boolean{return actual > 2.4 && actual < 3.7;}});
   
   //find with RegExp.
   var moviesTheBeginWithTr:Array = at.asearch(movies,{name:new RegExp('^Tr.)});
   
   //find with sub-array query (assuming the 'cast' property returns an Array of Actors with the property 'name').
   var moviesWithMeganFox:Array = at.asearch(movies,{'cast.name':'Megan Fox'});

Supported properties in the "options" parameter.

asearchAll()method 
public function asearchAll(array:Array, conditions:Object):Array

Shortcut for advanced searching by a single property.

Parameters
array:Array — The array to search in.
 
conditions:Object — An object defining the conditions to use in the search.

Returns
Array
asearchBy()method 
public function asearchBy(array:Array, property:String, value:Object, options:* = null):*

Shortcut for advanced searching by a single property.

Parameters
array:Array — The array to search in.
 
property:String — The property to read.
 
value:Object — The value of the target property.
 
options:* (default = null) — Find An object with find property. {find:"first"|"last"|"all"}.

Returns
*
asearchFirst()method 
public function asearchFirst(array:Array, conditions:Object):*

Shortcut for advanced searching for the first matching item.

Parameters
array:Array — The array to search in.
 
conditions:Object — An object defining the conditions to use in the search.

Returns
*
asearchLast()method 
public function asearchLast(array:Array, conditions:Object):*

Shortcut for advanced searching for the last matching item.

Parameters
array:Array — The array to search in.
 
conditions:Object — An object defining the conditions to use in the search.

Returns
*
clone()method 
public function clone(array:Array):Array

Clones an array.

Parameters
array:Array — The array to clone.

Returns
Array
compare()method 
public function compare(a:Array, b:Array, ordered:Boolean = false):Boolean

Compare two arrays to see if their values (and optionally order) are identical.

Parameters
a:Array — Whether or not the arrays will be sorted before the compare is performed.
 
b:Array
 
ordered:Boolean (default = false)

Returns
Boolean

Example
Using ArrayUtils.compare: 
 
   var a:Array = [5,4,3,2,1,'C','B','A'];
   var b:Array = ['A','B','C',1,2,3,4,5];
   trace("arrays (unordered) compare: " + ArrayUtil.compare(a,b)); //true
   trace("arrays (ordered) compare: " + ArrayUtil.compare(a,b,true)); //false

contains()method 
public function contains(a:Array, element:Object):Boolean

Determines if a value exists within the array.

Parameters
a:Array — The array to search.
 
element:Object — The element to search for.

Returns
Boolean
equals()method 
public function equals(arr1:Array, arr2:Array):Boolean

Determine if one array is identical to the other array.

Parameters
arr1:Array — The first array.
 
arr2:Array — The second array.

Returns
Boolean
gi()method 
public static function gi():ArrayUtils

Singleton access.

Returns
ArrayUtils
insert()method 
public function insert(a:Array, element:Object, index:int):Array

Insert an element into an array at a specific index.

Parameters
a:Array — The array to insert an element into.
 
element:Object — The object to insert.
 
index:int — The index the object will be inserted into.

Returns
Array
locatePropVal()method 
public function locatePropVal(a:Array, prop:String, val:Object, caseInsensitive:Boolean = false):Object

Search for a unique property/value match in an array of complex objects.

Parameters
a:Array — An array of objects.
 
prop:String — The object property who's value will be tested.
 
val:Object — The value to match.
 
caseInsensitive:Boolean (default = false) — Whether or not prop and val should be case-insensitive (only if search val is a String).

Returns
Object
locatePropValIndex()method 
public function locatePropValIndex(a:Array, prop:String, val:Object, caseInsensitive:Boolean = false):int

Search for a unique property/value match in an array of complex objects and return its index in the array.

Parameters
a:Array — An array of objects.
 
prop:String — The object property who's value will be tested.
 
val:Object — The value to match.
 
caseInsensitive:Boolean (default = false) — Whether or not prop and val should be case-insensitive (only if search val is a String).

Returns
int
matchValues()method 
public function matchValues(a:Array, b:Array):Boolean

Compares two arrays to see if any two indexes have the same value as the other array.

Parameters
a:Array — The first array.
 
b:Array — The second array.

Returns
Boolean
maxIndex()method 
public function maxIndex(a:Array):int

Return the array index of the maximum value in a numeric array.

Parameters
a:Array — The array to search.

Returns
int
maxVal()method 
public function maxVal(a:Array):Number

Return the maximum value in a numeric array.

Parameters
a:Array — The array to search.

Returns
Number
merge()method 
public function merge(a:Array, b:Array):Array

Merge two arrays into one.

Parameters
a:Array — The first array.
 
b:Array — The second array.

Returns
Array
minIndex()method 
public function minIndex(a:Array):int

Return the array index of the minimum value in a numeric array.

Parameters
a:Array — The array to search.

Returns
int
minValue()method 
public function minValue(a:Array):Number

Return the minimum value in a numeric array.

Parameters
a:Array — The array to search.

Returns
Number
nearestNeighbor()method 
public function nearestNeighbor(val:Number, range:Array, returnIndex:Boolean = false):Number

Locate and return the (lowest) nearest neighbor or matching value in a NUMERIC sorted array of Numbers.

Parameters
val:Number — the value to find match or find nearst match of.
 
range:Array — of values in array.
 
returnIndex:Boolean (default = false) — if true return the array index of the neighbor, if false return the value of the neighbor.

Returns
Number

Example
Using ArrayUtils.nearestNeighbor: 
   var a:Array = [1, 3, 5, 7, 9, 11];
   var nearestLow:Number = ArrayUtil.nearestNeighbor(4,a); //returns 3 (value)
   var nearestHigh:Number = ArrayUtil.nearestNeighbor(4,a,true); //returns 1 (index)

remove()method 
public function remove(a:Array, element:Object):Array

Remove all instances of an element from an array.

Parameters
a:Array — The array to search and remove from.
 
element:Object — The element to remove from the array.

Returns
Array
removeDuplicate()method 
public function removeDuplicate(a:Array):Array

Remove duplicates from an array and return a new array.

Parameters
a:Array — The array to remove duplicates from.

Returns
Array
shuffle()method 
public function shuffle(a:Array):void

Shuffle array elements.

Parameters
a:Array — The array to shuffle.
sliceByPropVal()method 
public function sliceByPropVal(a:Array, prop:String, val:Object, caseInsensitive:Boolean = false):Array

Return a new array sliced from the original array of complex objects based on a prop/val match

Parameters
a:Array — An array of objects.
 
prop:String — The object property who's value will be tested.
 
val:Object — The value to match.
 
caseInsensitive:Boolean (default = false) — Whether or not prop and val should be case-insensitive (only if search val is a String).

Returns
Array
swap()method 
public function swap(a:Array, index1:int, index2:int):Array

Swap two element's positions in an array.

Parameters
a:Array — The target array in which the swap will occur.
 
index1:int — The first index.
 
index2:int — The second index.

Returns
Array
uniqueCopy()method 
public function uniqueCopy(a:Array):Array

Create a new array that contains unique instances of objects. This can be used to remove duplication object instances from an array.

Parameters
a:Array — The array to uniquely copy.

Returns
Array