VEGAS JS

Namespace: arrays

core. arrays

The core.arrays package is a modular JavaScript library that provides extra Array methods.

Author:
License:

Methods

contains(ar, value)

Determines whether the specified object exists as an element in an Array object.

Parameters:
Name Type Description
ar Array

The search Array.
value *

The object to find in the array.
Returns:

true if the specified object exists as an element in the array ; otherwise, false.

Example
var ar = [2, 3, 4] ;
trace( contains( ar , 3 ) ) ; // true
trace( contains( ar , 5 ) ) ; // false

initialize( [elements] [, value])

Initializes a new Array with an arbitrary number of elements (index), with every element containing the passed parameter value or by default the null value.

Parameters:
Name Type Argument Default Description
elements number <optional>
 1

The number of elements to fill the Array.
value * <optional>
 null

The value to inject in the Array.
Returns:

A new Array with an arbitrary number of elements (index), with every element containing the passed parameter value or by default the null value.

Example
ar = initialize( 3 ) ;
trace( ar ) ; // [ null , null , null ]

ar = initialize( 3 , 0 ) ;
trace( ar ) ; // [ 0 , 0 , 0 ]

ar = initialize( 3 , true ) ;
trace( ar ) ; // [ true , true , true ]

ar = initialize(  4 , "" ) ;
trace( ar ) ; // [ "" ,"" ,"" ,"" ]

pierce(ar, index, flag)

Splices an array (removes an element) and returns either the entire array or the removed element.

Parameters:
Name Type Description
ar Array

The array to pierce.
index number

The index of the array element to remove from the array (default 0).
flag boolean

A boolean true to return a new spliced array of false to return the removed element.
Returns:

The newly spliced array or the removed element in function of the flag parameter.

Example
var ar = [0,1,2,3,4,5] ;

trace( ar ) ; // 0,1,2,3,4,5

trace( "pierce( ar, 1 ) : " + pierce( ar, 1 ) ) ; // pierce(ar,1) : 1
trace( "pierce( ar, 1 ) : " + pierce( ar, 1 ) ) ; // pierce(ar,1) : 2

trace( ar ) ; // 0,3,4,5

trace( pierce( ar, 1 , true ) ) ; // 0,4,5

repeat(ar, count)

Returns a new Array who contains the specified Array elements repeated count times.

Parameters:
Name Type Description
ar Array

The array to repeat.
count number

The number of repeat.
Returns:

A new Array who contains the specified Array elements repeated count times.

Type
Array
Example
trace( repeat( [2, 3, 4] , 0 ) ) ; // 2,3,4
trace( repeat( [2, 3, 4] , 3 ) ) ; // 2,3,4,2,3,4,2,3,4

rotate(ar [, amount])

Rotates an Array in-place. After calling this method, the element at index i will be the element previously at index(i-n)%array.length, for all values of i between 0 and array.length-1, inclusive.

For example, suppose list comprises [l, o, v, e]. After invoking rotate(array, 1) (or rotate(array, -3)), array will comprise [e,l,o,v].

Parameters:
Name Type Argument Default Description
ar Array

The array to rotate.
amount number <optional>
 1

The amount to rotate.
Returns:

The rotated Array reference.

Type
Array
Example
var array = ["l","o","v","e"] ;

trace( dump( rotate( array ,  1 ) ) ) ; // ["e","l","o","v"]
trace( dump( rotate( array , -1 ) ) ) ; // ["l","o","v","e"]
trace( dump( rotate( array , -1 ) ) ) ; // ["o","v","e","l"]
trace( dump( rotate( array ,  3 ) ) ) ; // ["v","e","l","o"]

shuffle(ar)

Shuffles an array.

Parameters:
Name Type Description
ar Array

The array to shuffle.
Returns:

the shuffled array.

Type
Array
Example
var = [0,1,2,3,4,5,6,7,8,9] ;
trace( ar ) ;
shuffle( ar ) ;
trace( ar ) ;

sortOn()

Sorts the elements in an array according to one or more fields in the array. The array should have the following characteristics:

  • The array is an indexed array, not an associative array.
  • Each element of the array holds an object with one or more properties.
  • All of the objects have at least one property in common, the values of which can be used to sort the array. Such a property is called a field.
Example
var echo = function( a )
{
    var l = a.length ;
    for (var i = 0; i < l; i++)
    {
        trace( ">> " + a[i].name + " :: " + a[i].num ) ;
    }
}

trace ("---- Array") ;
var a =
[
    { name:"test 0" , num:6 } ,
    { name:"Test 1" , num:8 } ,
    { name:"test 2" , num:4 } ,
    { name:"test 3" , num:10 }
] ;

echo(a) ;

trace ("---- sort num Array.NUMERIC | Array.DESCENDING") ;

var r = sortOn( a , "num", Array.NUMERIC | Array.DESCENDING) ;

echo(a) ;

trace ("---- sort name") ;

sortOn( a , "name") ;

echo(a) ;

trace ("---- sort name Array.CASEINSENSITIVE") ;

sortOn( a , "name", Array.CASEINSENSITIVE) ;

echo(a) ;

trace ("---- sort name Array.RETURNINDEXEDARRAY") ;

//var result = sortOn( a , "name", Array.CASESEINSENTIVE | Array.RETURNINDEXEDARRAY) ;
//var result = sortOn( a , "name", Array.RETURNINDEXEDARRAY) ;
//trace (result) :

var result = sortOn( a , "num", Array.NUMERIC | Array.DESCENDING | Array.RETURNINDEXEDARRAY ) ;
trace (result) ;

var result = sortOn( a , "num", Array.NUMERIC | Array.RETURNINDEXEDARRAY ) ;
trace (result) ;

var result = sortOn( a , "name", Array.NUMERIC | Array.RETURNINDEXEDARRAY ) ;
trace (result) ;

trace ("---- sort name Array.UNIQUESORT") ;

a.push({ name:"test 1" , num:60 } ) ;

sortOn( a , "name", Array.UNIQUESORT ) ;

echo(a) ;

spliceInto(inserted, container, position, count)

Splice one array into another.

Parameters:
Name Type Description
inserted array

The Array of values inserted in the Array container.
container array

The container modified in place.
position number

The position in the container to inserted the Array of chars.
count number

The count value to replaced values.
Example
inserted  = [1, 2, 3, 4] ;
container = [5, 6, 7, 8] ;

trace( "inserted  : " + inserted  ) ;
trace( "container : " + container ) ;

trace("---") ;

inserted  = [1, 2, 3, 4] ;
container = [5, 6, 7, 8] ;

spliceInto( inserted, container ) ;

trace( "spliceInto( inserted, container, 0 , 0 ) : " + container ) ; // 1,2,3,4,5,6,7,8

trace("---") ;

inserted  = [1, 2, 3, 4] ;
container = [5, 6, 7, 8] ;

spliceInto( inserted, container, 0 , 4 ) ;

trace( "spliceInto( inserted, container, 0 , 4 ) : " + container ) ; // 1,2,3,4

trace("---") ;

inserted  = [1, 2, 3, 4] ;
container = [5, 6, 7, 8] ;

spliceInto( inserted, container, 0 , 2 ) ;

trace( "spliceInto( inserted, container, 0 , 2 ) : " + container ) ; // 1,2,3,4,7,8

swap(ar [, from] [, to] [, clone])

Swaps two indexed values in a specific array representation.

Parameters:
Name Type Argument Default Description
ar Array

The Array of values to change.
from number <optional>
 0

The first index position to swap.
to number <optional>
 0

The second index position to swap.
clone boolean <optional>
 false

Returns a swaped clone of the passed-in array.
Example
var ar = [ 1 , 2 , 3 , 4 ] ;
trace( ar ) ; // 1,2,3,4
swap( ar , 1 , 3 ) ;
trace( ar ) ; // 1,4,3,2