| THE META-HTML LANGUAGE REFERENCE MANUAL

Variables | [TOC] | Packages

## Section Intro: Arrays

Synopsis:

Meta-HTML allows the use of array variables as well as single element variables. In fact, all string variables in Meta-HTML can be treated as array variables -- there is no special command for creating such variables.

Commands:

array-add-unique array-append array-concat | array-member array-shift array-size | foreach sort

More Information:

Array variable values are referenced by placing the array index directly after the variable name, enclosed in square brackets ([ and ]). Thus, a reference to the 3rd element of the array FOO looks like:

       foo[3]

When an array reference is made without any containing index, the reference refers to the entire array. So, to get the value of the entire array stored in FOO, you would write:

       <get-var foo[]>

In order to ease the writing of array references which rely on a variable index, a variable name seen as an array reference index is automatically looked up as if you had written `<get-var VAR>`. Finally, multiple values may be given in a `set-var` command by separating those values with newline characters. The following sequence of commands illustrates the typical use of array variables.

    <set-var array[] =
           "value-zero
            value-one
            value-two
            value-three">
        <set-var i=0>
        <while <get-var array[i]>>
          The value of array[<get-var i>] is `<get-var array[i]>'.<br>
          <increment i>
        </while>

produces:

    The value of array[0] is `value-zero'.

              The value of array[1] is `value-one'.

              The value of array[2] is `value-two'.

              The value of array[3] is `value-three'.

### Function Documentation

`<array-add-unique ITEM ARRAYVAR [CASELESS=TRUE]>` | Simple

Adds ITEM as the last array element of the contents of ARRAYVAR if, and only if, ITEM is not already a member of that array.

The comparison is a direct string-wise compare. If CASELESS is non-empty, then a caseless string compare is done.

See also `array-append`.

`<array-append ITEM ARRAYVAR>` | Simple

Adds ITEM as the last array element of the contents of ARRAYVAR. This is especially useful in conjunction with `foreach` as a collector:

    <foreach name allnames>
      <if <satifies-criteria <get-var name>>
         <array-append <get-var name> useful-names>>
    </foreach>

See also `array-add-unique`.

`<array-concat RECEIVER [CONTRIBUTOR...]>` | Simple

Appends the contents of each CONTRIBUTOR array to the end of RECEIVER.

Both RECEIVER and each are variable names whose values are treated as arrays.

For a single CONTRIBUTOR, `array-concat` could have been defined as:

    <defsubst array-concat>
      <foreach item %1>
         <array-append <get-var item> %0>
      </foreach>
    </defsubst>

`<array-member ITEM ARRAYVAR [CASELESS=TRUE]>` | Simple

Looks up (and returns) the index of ITEM in the contents of the array referenced by ARRAYVAR.

If ITEM is not found, then `array-member` returns the empty string.

If CASELESS is non-empty, then the comparison is done without regard to character case. Otherwise, character case is significant in the location of the item.

    <set-var array[] =
      <prog
         this
         another
         multi word
         thing>>
    <array-member "multi word" array>

produces:

    2

`<array-shift AMOUNT ARRAYVAR>` | Simple

Shift the elements of ARRAYVAR the indicated amount.

If AMOUNT is negative, the elements are shifted down (i.e. towards zero), with the lowest number elements being lost.

If AMOUNT is positive, the elements are shifted up, with no loss at all -- instead empty elements are used to fill the created space.

Given the array:

    <set-var array[] =
       <prog
           0
           1
           2>>

then after executing `<array-shift 2 array>`, the array looks like:

       ""
       ""
       "0"
       "1"
       "2"

and, a subsequent execution of `<array-shift -3 array>` leaves ARRAY:

       "1"
       "2"

`<array-size ARRAYVAR>` | Simple

Returns the number of elements in the array referenced by the variable ARRAYVAR.

Examples:

    <set-var array[]="this">
    <array-size array>

produces:

    1

and,

    <array-shift 4 array>
    <array-size array>

produces:

    5

`<foreach ELEMENTVAR ARRAYVAR [START=X] [END=X] [STEP=X]> body </foreach>` | Complex

Perform BODY with ELEMENTVAR bound to successive memebers of ARRAYVAR, starting with the element at START (default 0), and ending at END (default `<array-size ARRAYVAR>`), advancing by STEP (default 1).

The `foreach` command is the basic array looping device in Meta-HTML. It is guaranteed to iterate over each element that you specify, whether that element is the empty string or not.

Starting with the simple array:

    <set-var array[]="0\n1\n2\n3\n4\n5\n6\n7\n8\n9">

we can print out the odd numbers of this array by using values for both START and STEP:

    <foreach x array start=1 step=2> <get-var x>, </foreach>

produces:

    1,  3,  5,  7,  9,

or, we can produce a "countdown" with a negative value for STEP:

    <foreach x array step=-1> <get-var x>, </foreach> BOOM!

produces:

    9,  8,  7,  6,  5,  4,  3,  2,  1,  0,  BOOM!

`<sort ARRAYVAR [SORT-FUN] [CASELESS=TRUE] [SORTORDER=REVERSE] [NUMERIC=TRUE]>` | Simple

Sort the contents of the array ARRAYVAR.

The elements are sorted in place -- this function has no return value.

If CASELESS=TRUE is given, then the comparison of the elements of the array is done without regards to case.

If SORTORDER=REVERSE is given, then the results are returned in descending order, instead of ascending order. The default is to order the elements in ascending order.

If NUMERIC=TRUE is given, then the elements of ARRAYVAR are treated as numeric entities, whether they are or not. The default is to treat the elements as character strings, which can have unexpected results when sorting numeric quantities ("11" is less then "2" when sorting alphabetically!)

Finally, you may supply a sorting function, whose name is passed as SORT-FUN. This function will be called on each element just before comparison, and the results of that function will be used for the comparison instead of the element itself. This allows you to create a collating sort, or to sort on complex weighting features, or anything else that you can conceive of.

Examples:

Given the array:

    <set-var array[0] = 1
             array[1] = 2
             array[3] = 3
             array[4] = 4
             array[5] = 20>

then,

    <sort array>
    <foreach x array> <get-var x> </foreach>

produces:

    1  2  2  20  3  4  6  7  8  9

while

    <sort array numeric=true>
    <foreach x array> <get-var x> </foreach>

produces:

    1  2  2  3  4  6  7  8  9  20

Sorting strings:

    <set-var array[]="a\nb\nc\nd\ne\nf\nA\nB\nC\nD\nE\nF">
    <sort array sortorder=descending>
    <foreach x array> <get-var x> </foreach>

produces:

    f  e  d  c  b  a  F  E  D  C  B  A

Without regards to case:

    <sort array caseless=true>
    <foreach x array> <get-var x> </foreach>

produces:

    a  A  b  B  c  C  d  D  e  E  f  F

Finally, here is an example which sorts a list of words based upon the percentage of vowels present in each word, using a sort function which calculates that value for each string:

    <defun vowel-percentage string>
      <set-var x =
        <subst-in-string <downcase <get-var string>> "([^aeiou])" "">>
      <percent <string-length <get-var x>>
               <string-length <get-var string>>>
    </defun>
    .blank
    <set-var words[]=
      <prog
        Brian
        Fox
        sorts
        elegant
        strings
        beautifully>>
    .blank
    <sort words vowel-percentage numeric=true sortorder=descending>
    .blank
    <foreach word words>
      <get-var word> (<vowel-percentage <get-var word>>)<br>
    </foreach>

produces:

    beautifully (45.45)
      elegant (42.92)
      Brian (40.00)
      Fox (33.33)
      sorts (20.00)
      strings (14.29)

Edit Section
Function Index
Variable Index

The META-HTML Reference Manual V1.4 Copyright © 1995, 1996, Brian J. Fox, 1996, 1997 Universal Access Inc.
Found a bug? Send mail to bug-manual@metahtml.com