Section Intro: Arrays
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.
Array variable values are referenced by placing the array index directly after the variable name, enclosed in square brackets ([ and ]). Array references use a zero-base index, so that the first accessible element in the array is at index 0 and a reference to the 4th accessible element of the array FOO looks like:
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:
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
<set-var array = "value-zero value-one value-two value-three"> <set-var i=0> <while <get-var-once array[i]>> The value of array[<get-var-once i>] is `<get-var-once array[i]>'.<br> <increment i> </while>produces:
The value of array is `value-zero'.
Add 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.
If the keyword argument TELLME is supplied with a non-null value, then this function returns the word "true" if the item was added, or the empty string if not.
Add ITEM as the last array element of the contents
of ARRAYVAR. This is especially useful in conjunction with
<foreach name allnames> <if <satifies-criteria <get-var-once name>> <array-append <get-var-once name> useful-names>> </foreach>
Appends the contents of each CONTRIBUTOR array to the end of RECEIVER.
Both RECEIVER and each CONTRIBUTOR are variable names whose values are treated as arrays.
For a single CONTRIBUTOR,
<defsubst array-concat dest-name source-name> <foreach item <get-var-once source-name>> <array-append <get-var-once item> <get-var-once dest-name>> </foreach> </defsubst>
Delete the element of ARRAYVAR indicated by INDEX. The remainder of the array after INDEX is shifted back by one, so that the array ends up with one less element than it had before.
Return the intersection of the two arrays represented by the variables ARRAY1 and ARRAY2. For example:
<set-var a1=0 a1=1 a1=2 a2=2 a2=3 a2=4> <array-intersection a1 a2>produces:
Look up (and return) the index of ITEM in the contents of the array referenced by ARRAYVAR.
If ITEM is not found, then
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.
If a function name is passed, as in COMPARE=FUNC, it should be the name of a function which receives two required arguments -- the item that is to be looked for, and an element of the array that this item is to be compared against, and an optional keyword argument of "caseless". If the function returns a non-empty string, then this item is considered a match.
By default, string comparison is done on the elements.
<set-var array = <prog this another multi word thing>> <array-member "multi word" array>produces:
Directly modify the values of ARRAYVAR making the first element be the last, and the last be the first.
<set-var array="0 1 2 3"> <array-reverse array> <get-var-once array>produces:
3 2 1 0
Return the section of the array in ARRAYVAR which starts at index offset BEG and continues until index offset END.
BEG defaults to zero (i.e., the beginning of the array), and
END defaults to the size of the array (see also
If BEG is greater than END, the elements of the array are returned in reverse order, starting from the ENDth element.
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.
If the keyword argument START is present, it indicates the zero-based offset from which to start shifting.
Given the array:
<set-var array = <prog 0 1 2>>
then after executing
"" "" "0" "1" "2"and, a subsequent execution of
Returns the number of elements in the array referenced by the variable ARRAYVAR.
<set-var array="this"> <array-size array>produces:
<array-shift 4 array> <array-size array>produces:
Return the union of the two arrays represented by the variables ARRAY1 and ARRAY2. For example:
<set-var a1=0 a1=1 a1=2 a2=2 a2=3 a2=4> <array-union a1 a2>produces:
0 1 2 3 4
Produce a human readable string of the elements in the array variable ARRAYVAR separated by commas where appropriate, and with the word "and" after the penultimate item.
Perform BODY with ELEMENTVAR bound to successive memebers
of ARRAYVAR, starting with the element at START (default
0), and ending at END (default
If NO-COPY=TRUE is specified, the array is not copied before iteration, so that changes that you make to the array take place immediately, during the execution of the surrounding <foreach>.
Starting with the simple array:
we can print out the odd numbers of this array by using values for both START and STEP:
<foreach x example::array start=1 step=2> <get-var-once x>, </foreach>produces:
1, 3, 5, 7, 9,
or, we can produce a "countdown" with a negative value for STEP:
<foreach x example::array step=-1> <get-var-once x>, </foreach> BOOM!produces:
9, 8, 7, 6, 5, 4, 3, 2, 1, 0, BOOM!
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.
Given the array:
<set-var array = 1 array = 2 array = 3 array = 4 array = 20>then,
Without regards to case:
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-once string>> "([^aeiou])" "">> <percent <string-length <get-var-once x>> <string-length <get-var-once string>>> </defun> <set-var words= <prog Brian Fox sorts elegant strings beautifully>> <sort words vowel-percentage numeric=true sortorder=descending> <foreach word words> <get-var-once word> (<vowel-percentage <get-var-once word>>)<br> </foreach>produces:
Sort the CORRELATED-ARRAYS based on the results of sorting
KEYARRAY. Also see
The META-HTML Reference Manual V2.0 Copyright © 1995, 1998, Brian J. Fox
Found a bug? Send mail to firstname.lastname@example.org