Array Class Reference
[ECMAScript/QtScript - Native Objects]

ECMAScript Array prototype object. More...

Inheritance diagram for Array:

Object List of all members.

Properties

Number length

Constructors

 Array (Object firstElement[,...])
 Array (Number len)
 Array ()

Methods (ECMAScript)

Array concat (Object element1[,...])
String join (String separator=",")
Object pop ()
Number push (Object element1[,...])
Array reverse ()
Object shift ()
Array slice (Number startIndex, Number endIndex=length)
Array sort (function comparisonFunction)
Array splice (Number startIndex, Number replacementCount[,...])
String toLocaleString ()
String toString ()
Array unshift (Object element1[,...])

Methods (DAZ Script 2 Extensions)

Number find (Object element)
Number pushIfNotExists (Object element1[,...])

Detailed Description

ECMAScript Array prototype object.

An Array is a data type that allows you to work with a list of elements. These elements can be any QObject derived object. Multi-dimensional arrays are achieved by using array elements that are arrays themselves.

Array Creation
Arrays can be constructed using array literals, or by using the new operator. They can be extended dynamically by simply creating elements at non-existant index positions.

Example:
Array literal
    var aTmp = [];

Example:
Array literal
    var aTmp = [ "a", "b", "c", "d" ];

Example:
Using the new operator, initialized with a size, but with undefined elements
    var aTmp = new Array( 4 );

Example:
Using the new operator, defining all elements
    var aTmp = new Array( "a", "b", "c", "d" );

Example:
Multi-Dimensional, dynamically extended
    var aTmp = new Array( "a", "b", "c", "d" );
    var aTmp2 = new Array;
    // aTmp2 == []
    
    for ( var i = 0; i < aTmp.length; i++ ) {
        aTmp2[ i ] = new Array( 2 );
        aTmp2[ i ][ 0 ] = i;
        aTmp2[ i ][ 1 ] = aTmp[ i ];       
    }
    // aTmp2 == [ [ 0, "a" ], [ 1, "b" ], [ 2, "c" ], [ 3, "d" ] ]

Array Access
Array elements are accessed by their names. Names can be integers or strings. As integers, element names are zero-based, meaning the first element is at 0, the second element is at 1 and so on. As strings, elements can act as normal properties, and can be accessed by using the square bracked operator ([]) or by directly dereferencing the Array object and specifying the property name (.name). These two accessor types can be mixed freely.

Example:
Integer access
    var aTmp = new Array( "a", "b", "c", "d" );
    var sTmp = aTmp[ 2 ];
    // sTmp == "c";

Example:
Multi-Dimensional, integer access
    var aTmp = new Array( [ "a", 5 ], [ "b", 10 ], [ "c", 15 ], [ "d", 20 ] );
    var nTmp = aTmp[ 2 ][ 1 ];
    // nTmp == 15;

Example:
String access, using the square bracked operator
    var aTmp = [];

    // Assignment:
    aTmp[ "one" ] = "a";
    aTmp[ "two" ] = "b";

    // Retrieval:
    var sTmp = aTmp[ "one" ];
    // sTmp == "a"
    var sTmp2 = aTmp[ "two" ];
    // sTmp2 == "b"

Example:
String access, dereferencing the Array, specifying properties
    var aTmp = [];

    // Assignment:
    aTmp.one = "a";
    aTmp.two = "b";

    // Retrieval:
    var sTmp = aTmp.one;
    // sTmp == "a"
    var sTmp2 = aTmp.two;
    // sTmp2 == "b"

Array Iteration
An Array can be iterated over by using a for or for...in loop.

Example:
Iteration of element names as integers, using the for control statement
    var aTmp = new Array( "a", "b", "c", "d" );
    var sTmp = new String;

    for( var i = 0; i < aTmp.length; i++ ){
        sTmp += aTmp[ i ];
    }
    // sTmp == "abcd"

Example:
Iteration of element names as strings, using the for...in control statement
    var aTmp = new Array;
    aTmp[ "first" ] = "a";
    aTmp[ "second" ] = "b";
    aTmp[ "third" ] = "c";
    aTmp[ "fourth" ] = "d";
    // element names are sorted alphanumericically
    // aTmp == [ "first" : "a", "fourth" : "d", "second" : "b", "third" : "c" ]

    var sTmp = new String;

    for( var i in aTmp ){
        sTmp += aTmp[ i ];
    }
    // sTmp == "adbc"

Todo:
Investigate if the return value is a Qt bug; reference vs. copy: reverse, sort, slice.


Constructor & Destructor Documentation

Array::Array (  ) 

Default Constructor.

Example:
        var aTmp = new Array;

Array::Array ( Number  len  ) 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Constructs an array of the given length. The arrays elements will be uninitialized (undefined).

Parameters:
len The number of items in the new array

Array::Array ( Object  firstElement[,...]  ) 

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Constructs an array with one or more elements

Parameters:
firstElement The first element to add to the array.
... Additional elements to add to the array. (Optional)


Member Function Documentation

Array Array::concat ( Object  element1[,...]  ) 

Parameters:
element1 The first element to concatenate with the array.
... Additional elements to concatenate with the array. (Optional)
Returns:
A new Array consisting of the concatenated contents.
Example:
        var aTmp = new Array( "a", "b", "c" );
        var nTmp = 5;
        var aTmp2 = aTmp.concat( nTmp );
        // aTmp == [ "a", "b", "c" ]
        // aTmp2 == [ "a", "b", "c", 5 ]

        var aTmp = new Array( "a", "b", "c" );
        var aTmp2 = new Array( 1, 2, 3 );
        var aTmp3 = aTmp.concat( aTmp2 );
        // aTmp == [ "a", "b", "c" ]
        // aTmp2 == [ 1, 2, 3 ]
        // aTmp3 == [ "a", "b", "c", 1, 2, 3 ]

Number Array::find ( Object  element  ) 

Parameters:
element The item to search for in the array
Returns:
The index of element, if found. -1 if element is not found.
Example:
        var aTmp = new Array( "a", "b", "c", "d", "e" );
        var nTmp = aTmp.find( "d" );
        // nTmp == 3

String Array::join ( String  separator = ","  ) 

Parameters:
separator The character used to separate the elements in the list
Returns:
A String containing all elements in the array, with the given separator between each.
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        var sTmp = aTmp.join( ":" );
        // sTmp == "a:b:c:d"
See also:
toString()

Object Array::pop (  ) 

Removes the last (right-most) element from the array.

Returns:
The removed element
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        var sTmp = aTmp.pop();
        // aTmp == [ "a", "b", "c" ]
        // sTmp == "d"

Number Array::push ( Object  element1[,...]  ) 

Parameters:
element1 The first element to append to the array.
... Additional elements to append to the array. (Optional)
Pushes one or more elements onto the end (right) of the array.

Returns:
New length of the array.
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.push( "e" );
        // aTmp == [ "a", "b", "c", "d", "e" ]

Number Array::pushIfNotExists ( Object  element1[,...]  ) 

Parameters:
element1 The first element to append to the array.
... Additional element(s) to insert into the array. (Optional) Pushes one or more elements onto the end (right) of the array, if it doesn't already exist in the array.
Returns:
New length of the array.
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.pushIfNotExists( "e" );
        // aTmp == [ "a", "b", "c", "d", "e" ]

Array Array::reverse (  ) 

Reverses the order of the elements in the array.

Returns:
A reference to the Array.
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.reverse();
        // aTmp == [ "d", "c", "b", "a" ]

        var aTmp = new Array( "a", "b", "c", "d" );
        var aTmp2 = aTmp;
        aTmp.reverse();
        // aTmp == [ "d", "c", "b", "a" ]
        // aTmp2 == [ "d", "c", "b", "a" ]

Object Array::shift (  ) 

Removes the first (left-most) element in the array.

Returns:
The removed element.
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        var sTmp = aTmp.shift();
        // aTmp == [ "b", "c", "d" ]
        // sTmp == "a"

Array Array::slice ( Number  startIndex,
Number  endIndex = length 
)

Parameters:
startIndex The index of the first element in the slice.
endIndex The index of the element to end the slice at. Defaults to the length of the array. (Optional)
Returns:
A copy of the array from the element at startIndex to (but not including) the element at endIndex.
Example:
        var aTmp = new Array( "a", "b", "c", "d", "e", "f" );
        var aTmp2 = aTmp.slice( 2 );
        // aTmp == [ "a", "b", "c", "d", "e", "f" ]
        // aTmp2 == [ "c", "d", "e", "f" ]

        var aTmp = new Array( "a", "b", "c", "d", "e", "f" );
        var aTmp2 = aTmp.slice( 1, 4 );
        // aTmp == [ "a", "b", "c", "d", "e", "f" ]
        // aTmp2 == [ "b", "c", "d" ]

Array Array::sort ( function  comparisonFunction  ) 

Sorts the array using comparisonFunction. If no function is provided, default sorting is applied.

Parameters:
comparisonFunction The function to call to compare items in the array. (Optional)
Returns:
A reference to the Array.
Example:
No arguments
        var aTmp = new Array( "a", "c", "d", "b" );
        aTmp.sort();
        // aTmp == [ "a", "b", "c", "d" ]

Example:
Comparison function
        // -1 if a < b, 0 if a == b, 1 if a > b
        function numerically( a, b ){
            return a < b ? -1 : a > b ? 1 : 0;
        }

        var aTmp = new Array( 8, 90, 1, 4, 843, 221 );
        aTmp.sort( numerically );
        // aTmp == [ 1, 4, 8, 90, 221, 843 ]

Array Array::splice ( Number  startIndex,
Number  replacementCount[,...] 
)

Splices elements into the array.

Parameters:
startIndex The index in the array to place the new element(s).
replacementCount The number of elements in the array to replace.
... The element(s) to insert into the array. (Optional)
Returns:
A reference to the Array.
Example:
Insert
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.splice( 2, 0, "X" );
        // aTmp == [ "a", "b", "X", "c", "d" ]

        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.splice( 2, 0, "X", "Y" );
        // aTmp == [ "a", "b", "X", "Y", "c", "d" ]

Example:
Remove
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.splice( 2, 1 );
        // aTmp == [ "a", "b", "d" ]

Example:
Replace
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.splice( 2, 1, "X" );
        // aTmp == [ "a", "b", "X", "d" ]

        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.splice( 2, 1, "X", "Y" );
        // aTmp == [ "a", "b", "X", "Y", "d" ]

String Array::toLocaleString (  ) 

Provides a locale-aware version of toString()

Returns:
A String containing all elements of an array together, separated by a locale-specific separator.
See also:
toString(), join()

Reimplemented from Object.

String Array::toString (  ) 

Returns:
A String containing all elements of an array together, separated by commas. This method is used when the array is used in the context of string concatenation or is used as a text value (e.g. for printing).
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        var sTmp = aTmp.toString();
        // sTmp == "a,b,c,d"

See also:
join()

Reimplemented from Object.

Array Array::unshift ( Object  element1[,...]  ) 

Inserts the element(s) at the beginning (left) of the array.

Parameters:
element1 The first element to insert into the array.
... Additional element(s) to insert into the array. (Optional)
Returns:
A reference to the Array.
Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.unshift( "X" );
        // aTmp == [ "X", "a", "b", "c", "d" ]

        var aTmp = new Array( "a", "b", "c", "d" );
        aTmp.unshift( "X", "Y" );
        // aTmp == [ "X", "Y", "a", "b", "c", "d" ]


Member Data Documentation

Number Array::length

The number of elements in the array.

Example:
        var aTmp = new Array( "a", "b", "c", "d" );
        var nTmp = aTmp.length;
        // nTmp == 4


Generated on Thu Sep 24 12:21:10 2009

Copyright © 2002 - 2009 DAZ 3D, Inc.