Array Functions

• Below is a list of array-manipulation functions for simple arrays built into HFL.
• NOTE: These are normal functions, not object methods.
• Unless otherwise marked, the <array> argument of these functions must be an array primitive, not an array object. If you wish to use them on array objects, the value passed as the array argument must be the array object's .valueOf() value.
  • EXAMPLE

  • // Create an array object
    var arr = new Array(0, 1, 2);
    
    // Pop an element using pop() function
    $el = pop(arr1.valueOf());              // Array arr will now be [0, 1]
    
    // ... which is equivalent to using the pop() method
    $el = arr1.pop();                       // Array arr will now be [0]
    

• push (<array> , <elements>)

  where:

  <elements>

  :=

  <element> [, <element>]*
  • Adds one or more new elements to the end of the array, and returns the new length of the array.
  • EXAMPLE

  • var $arr = [0, 1, 2];
    
    // Insert three elements at the end of array $arr
    push($arr, 3, 4, 5);      // Array will now be [0, 1, 2, 3, 4, 5]
    

• pop (<array> [, <num-elements>])

  where:

  <elements>

  :=

  <element> [, <element>]*
  • Removes and returns one or more elements from the end of the array.
  • If <num-elements> is specified, removes that many elements from the array.
  • Otherwise removes the last element from the array.
  • EXAMPLE

  • var $arr = [0, 1, 2, 3, 4, 5];
    
    // Remove one element from the array
    var $el = pop($arr);                    // Array will now be [0, 1, 2, 3, 4]
    
    // Remove elements [2, 3, 4] from the array and store in array $arr3
    var $arr3 = pop($arr, 3);               // Array will now be [0, 1]
    

• unshift (<array> , <elements>)

  where:

  <elements>

  :=

  <element> [, <element>]*
  • Inserts one or more elements to the front of the array, and returns the new length of the array.
  • EXAMPLE

  • var $arr = [0, 1, 2];
    
    // Insert three elements at the beginning of array $arr
    unshift($arr, 3, 4, 5);      // Array will now be [3, 4, 5, 0, 1, 2]
    

• shift (<array> [, <num-elements>])

  where:

  <elements>

  :=

  <element> [, <element>]*
  • Removes and returns one or more elements from the front of the array.
  • If <num-elements> is specified, removes that many elements from the array.
  • Otherwise removes the first element from the array.
  • EXAMPLE

  • var $arr = [0, 1, 2, 3, 4, 5];
    
    // Remove one element from the array
    var $el = shift($arr);                  // Array will now be [0, 1, 2, 3, 4]
    
    // Remove elements [0, 1, 2] from the array and store in array $arr3
    var $arr3 = shift($arr, 3);             // Array will now be [3, 4]
    

• sort (<array> [, <compare-function>])

   

  where:

  <compare-function>

  :=

  asNums

  |

  reversed

  |

  bySubElements

  |

  <user-defined-function>
  • Returns a sorted copy of the array. It does not modify the original 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]
    var nums_sorted_as_strings = sort(nums);
    
    // Sort nums as numbers to [2, 9, 12, 80]
    var nums_sorted_as_nums = sort(nums, asNums);
    
    // Sort multi-dim array by first inner elements to [[1,2], [3,4], [5,6]]
    var multi_dim_sorted = sort(multi_dim, bySubElements);
    
    // Sort pets to ['cat', 'dog', 'fish', 'parrot']
    var pets_sorted = sort(pets);
    
    // Sort pet_names by first inner element using custom comparison function
    var pet_names_sorted = sort(pet_names, mysortfn);
    

• length (<array>)
  • Returns the number of elements in the array, or 0 if no elements.
  • EXAMPLE

  • var $arr = [0, 1, 2, 3, 4, 5];
    
    // Prints "Array has 6 elements"
    print("Array has "+length($arr)+" elements");
    

• arrayIndex (<array>, <value>])

  where:

  <value>

  :=

  a value that may be in the array
  • Returns the index of the value within the array if the value was found within the array, with the first element being index 0.
  • Returns -1 if the value was not found within the array.
  • EXAMPLE

  • var $arr = [0, 1, 2, 3, 'a', 'b', 'c'];
    
    // Sets $i = 2
    var $i = arrayIndex($arr, 2);
    
    // Sets $j = 5
    var $j = arrayIndex($arr, 'b');
    
    // Prints "Element 'd' not found" because 'd' not in array
    if (arrayIndex($arr, 'd') < 0)
      print("Element 'd' not found");
    

• arrayLastIndex (<array>, <value>])

  where:

  <value>

  :=

  a value that may be in the array
  • Returns the index of the last occurence of the value within the array if the value was found within the array, with the first element being index 0.
  • Returns -1 if the value was not found within the array.
  • EXAMPLE

  • var $arr = [0, 1, 2, 3, 2, 1];
    
    // Prints "Index of last '2' is 4"
    print("Index of last '2' is "+arrayLastIndex($arr, 2));
    
    // Prints "Index of last '3' is 3"
    print("Index of last '3' is "+arrayLastIndex($arr, 3));
    
    // Prints "Element 'd' not found" because 'd' not in array
    if (arrayLastIndex($arr, 'd') < 0)
      print("Element 'd' not found");
    

• arrayConcat (<array>, <array>] [, <array>]]*)
  • Concatenates two or more arrays and returns the result as a new array.
  • This does not modify the existing arrays.
  • EXAMPLE

  • var $arr1 = [0, 1, 2];
    var $arr2 = [3, 'a'];
    var $arr3 = ['b', 'c'];
    
    // Concatenate arrays to form new array = [0, 1, 2, 3, 'a', 'b', 'c']
    var $arr = arrayConcat($arr1, $arr2, $arr3);
    printArray("NEW ARRAY:", $arr);
    

    • RESULTS:

    • NEW ARRAY:
      -----------
      0
      1
      2
      3
      a
      b
      c
      -----------
      

• printArray (<label>, <array> [, <quote> [, <fNum> [, <iStart>]]])

  where:

  <label>

  :=

  Text string to be displayed as a banner

  <quote>

  :=

  Character to be used as a quote around elements

  <fNum>

  :=

  Boolean: if true lists element numbers in front

  <iStart>

  :=

  Starting index to be used instead of 0
  • Prints the contents of an array, with the <label> above the list as a banner header.
  • This function also works with Array objects.
  • If <quote> has a defined value, encloses each element with the specified character as a quote mark.
  • If <fNum> is true, numbers each element before its value.
  • If <iStart> is a numeric value, begins display with that element index instead of 0
  • EXAMPLES

  • var $sub_arr = ['b', 'c', 'd'];
    var $arr = [0, 'a', $sub_arr];
    
    // Display array in normal form
    printArray("NORMAL ARRAY DISPLAY", $arr);
    
    // Display array with elements enclosed in '|' character
    printArray("ELEMENTS IN QUOTES", $arr, '|');
    
    // Display array with elements quoted and numbered
    printArray("ELEMENTS IN QUOTES WITH LEADING NUMBERS", $arr, '|');
    
    // Display array with elements quoted and numbered, starting with element 2
    printArray("ELEMENTS IN QUOTES WITH LEADING NUMBERS FROM 2", $arr, '|', 2);
    

    • RESULTS:

    • NORMAL ARRAY DISPLAY
      -----------
      0
      a
      ARRAY(0x34b2280)
      4
      -----------
      
      ELEMENTS IN QUOTES
      -----------
      |0|
      |a|
      |ARRAY(0x34b2280)|
      |4|
      -----------
      
      ELEMENTS IN QUOTES WITH LEADING NUMBERS
      -----------
      0: |0|
      1: |a|
      2: |ARRAY(0x34b2280)|
      3: |4|
      -----------
      
      ELEMENTS IN QUOTES WITH LEADING NUMBERS FROM 2
      -----------
      2: |ARRAY(0x34b2280)|
      3: |4|
      -----------
      

• printArrayOfArrays (<label>, <array> [, <quote-char> [, <fNum>]])

  where:

  <label>

  :=

  Text string to be displayed as a banner

  <quote-char>

  :=

  Character to be used as a quote around elements

  <disp-flags>

  :=

  a hex number, where the bits mean:

  0x01

  :=

  Indent list after 1st element

  0x02

  :=

  Number the first level of elements

  0x04

  :=

  Number all levels of elements
  • Prints the contents of an array, with the <label> above the list as a banner header.
  • This function also works with Array objects.
  • If <quote-char> string has a defined value, encloses each element with the specified character on each side as a quote mark.
  • The <disp-flags> control how the array is displayed.
  • EXAMPLES

  • var $sub_arr = ['b', 'c', 'd'];
    var $arr = [0, 'a', $sub_arr];
    
    // Display array tree in normal form
    printArrayOfArrays("NORMAL ARRAY DISPLAY", $arr);
    
    // Display array tree with elements enclosed in '|' character
    printArrayOfArrays("ELEMENTS IN QUOTES", $arr, '|');
    
    // Display array tree with elements quoted and numbered
    printArrayOfArrays("ELEMENTS IN QUOTES WITH LEADING NUMBERS", $arr, '|', 0x4);
    

    • RESULTS:

    • NORMAL ARRAY TREE DISPLAY
      -----------
      0
      a
      >
        b
        c
        d
      4
      -----------
      
      ELEMENTS IN QUOTES
      -----------
      |0|
      |a|
      >
        |b|
        |c|
        |d|
      |4|
      -----------
      
      ELEMENTS IN QUOTES WITH LEADING NUMBERS
      -----------
      0:
      |0|
      1:
      |a|
      2:
      >
        0:
        |b|
        1:
        |c|
        2:
        |d|
      3:
      |4|
      -----------