Arbortext Command Language > Using the Arbortext Command Language > Arrays and Variables
  
Arrays and Variables
An array is a special type of variable because it can contain more than one value. An array consists of an array name and an index. The index identifies the element of the array that is addressed.
Arbortext Editor provides two types of one-dimensional arrays:
1. normal arrays — are indexed by integer subscripts
2. associative arrays —are indexed by arbitrary strings
You do not have to declare arrays or array elements or how many elements are in an array. When used in expressions, arrays are created when referenced in a manner similar to scalar variables. For example, as long as you have not already defined the scalar variable $a, then $a[1] = 'one' creates the array $a and assigns the string "one" to element 1.
Associative arrays are much like normal arrays except that subscripts are actually strings called keys. For example, $aa["one"] = 1 assigns the value 1 to the element with the key "one". A null subscript of an associative array is equivalent to a key of "0".
You can iterate over all the keys in an associative array using the for statement:
for (key in array)
For example, the following commands iterate over the two elements of the associative array price:
$price["candy"] = 45
$price["pop"] = $price["candy"] + 5
for ($junk in $price) {
$price[$junk] += 10;
}
A normal array is implemented internally using an array which dynamically expands if necessary as elements are added to it. An associative array is implemented using a hash table so lookups are fast regardless of the array size, but not as fast as a normal array. An associative array also usually requires more memory since each element has a fixed overhead due to the hash table.
Since the syntax for both normal and associative arrays is the same, Arbortext Editor decides which kind of array to use based on the subscript. If the subscript is an integer, a normal array is assumed. An associative array is used if the subscript is a string. If the array subscripts are all small integers but then a string subscript is used, Arbortext Editor will convert the array into an associative array. For example, with
arr[1] = 1
arr[2] = 2
arr["three"] = 3
the array arr starts off as a normal array but when the third assignment is executed, the array gets converted into an associative array. Arbortext Editor will also convert a normal array into an associative array if the array becomes sparse, that is, the majority of the elements are undefined. For example, with
arr[1] = 1
arr[2] = 2
arr[100000] = 100000
after the third statement, the array would become an associative array since considerably less memory would be needed to represent it. If you use integer subscripts with an associative array, it is more efficient to use a string subscript as the first reference. For example, preceding both examples above with
arr[" "] = " "
would avoid the conversion into an associative array.
When used in an expression, the subscript of an array may be an expression. The resulting value is used to access the array element. However, when used in variable substitution, the subscript may only be an integer constant (or string if an associative array), or a scalar variable. For example, the following command will not parse:
caret $pos[$i+1]
because $i+1 is an expression. This command can be rewritten, however, as
$i++;
caret $pos[$i]
Although you don't have to declare a global array variable, you can use the global statement to define it as follows:
global arr[]
The array arr can be either type of array, its subscripts determine whether it is a normal or associative array. The global statement can also be used to declare a fixed size normal array. For example:
global arr[10]
declares an array with 10 elements, indexed from 1 to 10. In this case, if you attempt to use a subscript not in this range, Arbortext Editor will issue an error message. You can specify a different starting subscript by using the notation global arr [lb ..hb]. For example:
global arr[-5..5]
defines an array with the lower bound -5 and higher bound 5. If you know the size of an array, it is more efficient to declare it as a fixed array of that size instead of letting the array dynamically expand. Most of the built-in functions that return arrays return fixed-size arrays.
The local statement can be used to declare local array variables and has the same syntax as global. The low_bound and high_bound built-in function return the bounds of a fixed-size array. The count built-in function returns the number of elements actually in use in either a normal or associative array.
The unsetvar command can be used to undefine an array, discarding its elements. For example:
unsetvar arr
deletes array $arr. Note that no leading dollar sign is used on the unsetvar command.
To delete an array element, use the delete built-in function. For example:
delete($arr[$i])
Deleting an element releases the memory for it and marks it undefined, both for normal and associative arrays. The built-in function count will return one less after the deletion. For a dynamic (non-fixed size) normal array, if you delete the first element of the array, the low_bound function will return the next valid index. If you delete the last element, high_bound will return the previous index.
The delete function may also be used to undefine an array, as in:
delete($arr)
Related Topics
Using expressions
Array membership expression
char_entity_names function
count function
delete function
join function
split function
tag_names function
user_tag_names function