Array Object

Creating Array objects using the 'new' operator

  • 'Array' objects can be created using the 'new' operator:
  • new Array([<elem> [, <elem>]*])
    new Array(<array-length>)
    • Per javascript standards, there are two syntaxes.
    • The first creates an Array object than contains one element for each <elem> data value specified.
    • The second creates an Array object that has the number of elements specified by the <array-length> argument, which must be an integer.
    • EXAMPLES:

      • // Two ways to create an array of 3 elements
        var arr1 = new Array('a', 'b', 'c');
        var arr2 = new Array(3);

Using array primitives as Array objects

  • Any array primitive may be used in place of an Array object to call Array methods or access Array object properties. HFL will promote the array primitive to an Array object, before calling the method or accessing the object property.
  • If an object property is assigned to an array primitive, the assignment will be ignored unless the array primitive was specified from a storage location such as a local or global variable, in which case it replaces the stored primitive array with the promoted Array object.
    • EXAMPLE:

      • var $arr = [1, 2, 3,4];

        // Prints "arr = [1, 2, 3, 4]"
        print("arr = $arr");

        // Promotes the array to an Array object then prints "Length is 4"
        print("Length is ".+$arr.length);

        // Setting an object property promotes the array primitive to an object
        $arr.type = "numbers";

        // Prints "typeof(arr) = object"
        print("typeof(arr) = ".+typeof($arr));

        // Still prints "arr = [1, 2, 3, 4]"
        print("arr = $arr");

Array Properties

  • <arr>.length
    • Returns the number of elements in the array.
    • EXAMPLE:

      • var arr1 = ['a', 'b', 'c'];

        // Prints "There are 3 elements"
        print("There are "+arr1.length+" elements");

Array Methods

  • <arr>.valueOf (<array>)
    • Returns the inner simple array of an Array object.
    • Simple arrays are more efficient to manipulate than array objects, as there is very little object overhead.
    • WARNING: If you pass the result of array.valueOf() to a non-method array-modifying function (such as pop()), the array.length value may be incorrect.
    • EXAMPLE

      • var arr_obj = new Array(0, 1, 2);
        var simple_array = arr_obj.valueOf();

  • <arr>.push([<elem> [, <elem>]*])
    • Adds one or more new elements to the end of the array, and returns the new length of the array.
    • EXAMPLE:

      • var arr1 = ['a', 'b', 'c'];

        // Array will be ['a', 'b', 'c', 'd', 'e'], len = 5
        var len = arr1.push('d', 'e');

  • <arr>.pop()
    • Removes and returns the last element in the array.
    • EXAMPLE:

      • var arr1 = ['a', 'b', 'c'];

        // Array will be ['a', 'b'], el = 'c'
        var el = arr1.pop();

  • <arr>.unshift([<elem> [, <elem>]*])
    • Inserts one or more elements to the front of the array, and returns the new length of the array.
    • EXAMPLE:

      • var arr1 = ['a', 'b', 'c'];

        // Array will be [1, 2, 3, 'a', 'b', 'c'], len = 6
        var len = arr1.unshift(1, 2, 3);

  • <arr>.shift()
    • Removes and returns the first element in the array.
    • EXAMPLE:

      • var arr1 = ['a', 'b', 'c'];

        // Array will be ['b', 'c'], el = 'a'
        var el = arr1.shift();

  • <arr>.sort([<compare-function>])
     
    where:
    <compare-function>
    :=
    asNums
    |
    reversed
    |
    bySubElements
    |
    <user-defined-function>
    • Sorts the array destructively, and returns the sorted array. By default, the elements will be sorted as strings, not values.
    • If the optional <compare-function> is not specified, the array will be sorted in Unicode code point order.
    • If the optional <compare-function> is specified, sort() will call it to calculate the collating order of the array elements.
    • As a convenience, HFL provides some built-in comparison functions, which are more efficient than user-defined ones.
      • asNums() will sort the array elements by numeric value, not string collation order.
      • reversed() will sort the array elements in reverse order.
      • bySubElements() will sort a muultiple-dimensional array by the first element of its component array elements, in forward order.
    • If a user-defined function <user-defined-function> is specified, it must take two arguments, one for each array element, and return a numeric value:
      • -1
        if the first element sorts before the second
         
        +1
        if the second element sorts before the first
         
        0
        if the two are to be left in original order
    • NOTE: If the array elements are integers, the default sorting order will be by their collating order, not their numeric value. Thus for example, 12 would sort before 2. To sort integers by value, use compare function asNums.
    • EXAMPLES

    • var nums = [12, 80, 2, 9];
      var multi_dim = [[5,6], [3,4], [1,2]];
      var pets = ['dog', 'cat', 'parrot', 'fish'];
      var pet_names = [['dog', 'fido'], ['cat', 'fluffy'], ['parrot', 'sam'],
                        ['fish', 'goldie']];

      function mysortfn($a, $b) {return cmp($a[0], $b[0]);}

      // Sort nums as strings to [12, 2, 80, 9]
      nums.sort();

      // Sort nums as numbers to [2, 9, 12, 80]
      nums.sort(asNums);

      // Sort multi-dim array by first inner elements to [[1,2], [3,4], [5,6]]
      multi_dim.sort(bySubElements);

      // Sort pets to ['cat', 'dog', 'fish', 'parrot']
      pets.sort();

      // Sort pet_names by first inner element using custom comparison function
      pet_names.sort(mysortfn);

Previous: String Object