|Home | Tutorial | Classes | Functions | QSA Workbench | Language | Qt API | QSA Articles | Qt Script for Applications |

[Prev: Built-in Types] [Home] [Next: Boolean]

#### Array

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.

##### Array Construction

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 Access

`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"];

##### Array Properties

- length : Number; Holds the number of items in the array. Items with string keys are excluded from the length property.

##### Array Functions

- 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]