|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 elements. The elements may be any Qt Script object. Multi-dimensional arrays are achieved by setting array elements to be arrays themselves.
Arrays can be extended dynamically simply by creating elements at non-existent index positions. Elements can also be added using push(), unshift() and splice(). Arrays can be concatenated together using concat(). Elements can be extracted using pop(), shift() and slice(). Elements can be deleted using splice(). Arrays can be turned into strings using join() or toString(). Use reverse() to reverse the elements in an array, and sort() to sort the elements. The sort() function can be passed a comparison function for customized sort orders.
In general, operations that copy array elements perform a deep copy on elements that are Number or String objects, and a shallow copy on other objects.
Arrays may 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 elements undefined:
var a = new Array( 10 ); // 10 elements
Array elements are accessed via their names. Names can be both integer indicies and strings.
Example:
var m2 = mammals[2]; mammals[2] = "gorilla"; var thing = things[2][1]
The first statement retrieves the value of the third element of the mammals array and assigns it to m2, which now contains "monkey". The second statement replaces the third element of the mammals array with the value "gorilla". The third statement retrieves the second element of the third element's array from the things array and assigns it to thing, which now contains "shrub".
As stated above, it is possible to access the arrays using strings as well. 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"];
Arrays have a single property, length, that holds the number of elements in the array.
concat( array1, array2, optArray3, ... optArrayN )
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 a number of arrays in the order given, and returns a single array.
join( optSeparator )
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 elements of an array together, separated by commas, or the specified optSeparator.
pop()
var x = new Array( "a", "b", "c" ); var y = x.pop(); // y == "c" x == [ "a", "b" ]
Pops the top-most (right-most) element off the array and returns this element.
See also push(), shift() and unshift().
push( element1, optElement2, ... optElementN )
var x = new Array( "a", "b", "c" ); x.push( 121 ); // x == [ "a", "b", "c", 121 ]
Pushes the given item(s) onto the top (right) end of the array. The function returns the new length of the array.
See also push(), shift() and unshift().
reverse()
var x = new Array( "a", "b", "c", "d" ); x.reverse(); // x == [ "d", "c", "b", "a" ]
Reverses the elements in the array.
shift()
var x = new Array( "a", "b", "c" ); var y = x.shift(); // y == "a" x == [ "b", "c" ]
Shifts the bottom-most (left-most) element off the array and returns this element.
See also push(), shift() and unshift().
slice( startIndex, optEndIndex )
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 element with the given starting index, startIndex, to the element before the element with the given ending index, optEndIndex. If no ending index is given, all elements from the starting index onward are sliced.
sort( optComparisonFunction )
var x = new Array( "d", "x", "a", "c" ); x.sort(); // x == [ "a", "c", "d", "x" ]
Sorts the elements 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, replacementCount, optElement1, ... optElementN )
var x = new Array( "a", "b", "c", "d" ); // 2nd argument 0, plus new elements ==> insertion x.splice( 1, 0, "X", "Y" ); // x == [ "a", "X", "Y", "b", "c", "d" ] // 2nd argument > 0, and no elements ==> deletion x.splice( 2, 1 ); // x == [ "a", "X", "b", "c", "d" ] // 2nd argument > 0, plus new elements ==> replacement x.splice( 3, 2, "Z" ); // x == [ "a", "X", "b", "Z" ]
Splices elements into the array and out of the array. The first argument, startIndex, is the start index. The second argument, replacementCount, is the number of elements that are to be replaced. Make the second argument 0 if you are simply inserting elements. The remaining arguments are the elements to be inserted; there can be no elements if you are simply deleting a part of the array, i.e. if the second argument is > 0.
toString()
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 elements 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, optExpression1, ... opExpressionN )
var x = new Array( "a", "b", "c" ); x.unshift( 121 ); // x == [ 121, "a", "b", "c" ]
Unshifts the given item(s) onto the bottom (left) end of the array.
See also push(), shift() and unshift().
[Prev: Built-in Types] [Home] [Next: Boolean]
Copyright © 2001-2003 Trolltech | Trademarks | QSA version 1.0.0
|