|Home | Tutorial | Classes | Functions | QSA Workbench | Language | Qt API | QSA Articles | Qt Script for Applications | ![]() |
[Prev: Built-in Types] [Home] [Next: Boolean]
An Array is a datatype which contains a named list of items. The items can be any Qt Script object. Multi-dimensional arrays are achieved by setting array items to be arrays themselves.
Arrays can be extended dynamically simply by creating items at non-existent index positions. Items can also be added using push(), unshift() and splice(). Arrays can be concatenated together using concat(). Items can be extracted using pop(), shift() and slice(). Items can be deleted using splice(). Arrays can be turned into strings using join() or Array::toString(). Use reverse() to reverse the items in an array, and sort() to sort the items. The sort() function can be passed a comparison function for customized sort orders.
In general, operations that copy array items perform a deep copy on items that are Number or String objects, and a shallow copy on other objects.
Arrays can be constructed from array literals or using the new operator:
var mammals = [ "human", "dolphin", "elephant", "monkey" ]; var plants = new Array( "flower", "tree", "shrub" ); var things = []; for ( i = 0; i < mammals.length; i++ ) { things[i] = new Array( 2 ); things[i][0] = mammals[i]; things[i][1] = plants[i]; }
Arrays can be initialized with a size, but with all items undefined:
var a = new Array( 10 ); // 10 items
Array items are accessed via their names. Names can be either integers or strings.
Example:
var m2 = mammals[2]; mammals[2] = "gorilla"; var thing = things[2][1]
The first statement retrieves the value of the third item of the mammals array and assigns it to m2, which now contains "monkey". The second statement replaces the third item of the mammals array with the value "gorilla". The third statement retrieves the second item of the third item's array from the things array and assigns it to thing, which now contains "shrub".
As stated above, it is also possible to access the arrays using strings. These act as normal properties, and can be accessed either 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 as seen below with the address and phoneNumber properties.
var names = []; names["first"] = "John"; names["last"] = "Doe"; var firstName = names["first"]; var lastName = names["last"]; names["address"] = "Somewhere street 2"; names.phoneNumber = "+0123456789"; var address = names.address; var phoneNumber = names["phoneNumber"];
length : Number; Holds the number of items in the array. Items with string keys are excluded from the length property.
concat( a1 : Array, a2 : Array ... aN : Array) : Array;
var x = new Array( "a", "b", "c" ); var y = x.concat( [ "d", "e" ], [ 90, 100 ] ); // y == [ "a", "b", "c", "d", "e", 90, 100 ]
Concatenates the array with one or more other arrays in the order given, and returns a single array.
join( optSeparator : String ) : String;
var x = new Array( "a", "b", "c" ); var y = x.join(); // y == "a,b,c" var z = x.join( " * " ); // y == "a * b * c"
Joins all the items of an array together, separated by commas, or by the specified optSeparator.
pop() : Object;
var x = new Array( "a", "b", "c" ); var y = x.pop(); // y == "c" x == [ "a", "b" ]
Pops (i.e. removes) the top-most (right-most) item off the array and returns it.
push( item1, optItem2, ... optItemN );
var x = new Array( "a", "b", "c" ); x.push( 121 ); // x == [ "a", "b", "c", 121 ]
Pushes (i.e. inserts) the given items onto the top (right) end of the array. The function returns the new length of the array.
reverse();
var x = new Array( "a", "b", "c", "d" ); x.reverse(); // x == [ "d", "c", "b", "a" ]
Reverses the items in the array.
shift() : Object;
var x = new Array( "a", "b", "c" ); var y = x.shift(); // y == "a" x == [ "b", "c" ]
Shifts (i.e. removes) the bottom-most (left-most) item off the array and returns it.
slice( startIndex : Number, optEndIndex : Number ) : Array;
var x = new Array( "a", "b", "c", "d" ); var y = x.slice( 1, 3 ); // y == [ "b", "c" ] var z = x.slice( 2 ); // z == [ "c", "d" ]
Copies a slice of the array from the item with the given starting index, startIndex, to the item before the item with the given ending index, optEndIndex. If no ending index is given, all items from the starting index onward are sliced.
sort( optComparisonFunction : function );
var x = new Array( "d", "x", "a", "c" ); x.sort(); // x == [ "a", "c", "d", "x" ]
Sorts the items in the array using string comparison. For customized sorting, pass the sort() function a comparison function, optComparisonFunction, that has the following signature and behavior:
function comparisonFunction( a, b ) // signature
The function must return an integer as follows:
-1 if a < b
0 if a == b
1 if a > b
Example:
function numerically( a, b ) { return a < b ? -1 : a > b ? 1 : 0; } var x = new Array( 8, 90, 1, 4, 843, 221 ); x.sort( numerically ); // x == [ 1, 4, 8, 90, 221, 843 ]
splice( startIndex : Number, replacementCount : Number, optItem1, ... optItemN );
var x = new Array( "a", "b", "c", "d" ); // 2nd argument 0, plus new items ==> insertion x.splice( 1, 0, "X", "Y" ); // x == [ "a", "X", "Y", "b", "c", "d" ] // 2nd argument > 0, and no items ==> deletion x.splice( 2, 1 ); // x == [ "a", "X", "b", "c", "d" ] // 2nd argument > 0, plus new items ==> replacement x.splice( 3, 2, "Z" ); // x == [ "a", "X", "b", "Z" ]
Splices items into the array and out of the array. The first argument, startIndex, is the start index. The second argument, replacementCount, is the number of items that are to be replaced. Make the second argument 0 if you are simply inserting items. The remaining arguments are the items to be inserted. If you are simply deleting items, the second argument must be > 0 (i.e. the number of items to delete), and there must be no new items given.
toString() : String;
var x = new Array( "a", "b", "c" ); var y = x.toString(); // y == "a,b,c" var z = x.join(); // y == "a,b,c"
Joins all the items of an array together, separated by commas. This function is used when the array is used in the context of a string concatenation or is used as a text value, e.g. for printing. Use join() if you want to use your own separator.
unshift( expression : String, optExpression1, ... opExpressionN )
var x = new Array( "a", "b", "c" ); x.unshift( 121 ); // x == [ 121, "a", "b", "c" ]
Unshifts (i.e. inserts) the given items at the bottom (left) end of the array.
[Prev: Built-in Types] [Home] [Next: Boolean]
Copyright © 2001-2006 Trolltech | Trademarks | QSA version 1.1.5
|