Any individual element within a variable, or any rectangular subset of a variable,
can be accessed directly using subscripts. Subscripts are entered in parentheses, which must come
immediately after the name of the variable (see VARIABLES[1]). The number of subscripts depends
on the dimensions of the variable. If there is more than one dimension, then the first subscript
represents the horizontal dimension and varies the fastest (except for STRING LIST variables,
see below). For each dimension, subscripts can either be a single value or a range of values
separated by a colon. NOTE: All subscripts start counting with 0 as the first element.
For example, suppose you have a matrix variable MM and a string variable SS containing:
mm = { ss = 'hiho silver'
1 2 3 4 5
6 7 8 9 10
20 30 40 50 60
}
You could access a single element in each as:
mm(2,1) is the number: 8 ss(8) is 'v'
or a range as:
mm(1,1:2) is an array: 7 30
mm(2:4,1:2) is a matrix: 8 9 10 ss(3:7) is 'o sil'
40 50 60
If any dimension has no subscript then the full range in that dimension is assumed. For example,
mm(2) is: 3 8 40
mm(,2) is: 20 30 40 50 60
If no value follows the colon then the range defaults to the end of the variable. For example,
mm(1:,1:) is: 7 8 9 10
30 40 50 60
Subscripts can be numbers, as in these examples, or they can be any CIGAL variable or arithmetic
expression that returns the equivalent of a number. For example, suppose that you are running
in graphics mode, in which case the internally declared image variable "@0" refers to the
graphics display region of video memory. Two useful internal variables are CURSX and CURSY,
which refer to the current X and Y positions of the cursor. Therefore,
@0(cursx,cursy)
refers to the pixel value at the current cursor position, whereas
@0(cursx-4:cursx+5,cursy-4:cursy+5)
refers to the 10 x 10 region of the display around the current cursor position. Moreover, you can
get the average intensity of the display at the cursor as:
mean(@0(cursx-4:cursx+5,cursy-4:cursy+5))
Vector Subscripts
VECTOR variables have somewhat unusual subscripts. Vectors are unusual in that they contain
6 elements of different sizes (see VARIABLES[1]). Because of this you are allowed access
to the whole vector, or to any single element, but a range can only select among the
first three elements (Xvalue,Yvalue, and Zvalue) because they are all the same size. For
example, if you have a vector VV, you can access:
vv ; the whole vector
vv(0) ; the Xvalue
vv(5) ; the intensity
vv(1:2) ; the Yvalue and Zvalue
but not:
vv(2:3) ; Zvalue and Key are incompatible
vv(3:4) ; Key and Width are incompatible
VECTOR LISTs obey the same rules as VECTORs, with the addition that the second subscript selects
which vectors. Thus, you can select from VECS (the internal vector list variable containing
the active display vectors) as, for example:
vecs(,10:20) ; the 11th through 21st vectors
vecs(1) ; all Yvalues
vecs(0,3) ; the Xvalue in the 4th vector
vecs(2,3:) ; the z values of all vectors after the third
String List Subscripts
STRING LIST variables also have unusual subscripts in that the order is reversed compared to
normal. Generally, the first subscript refers to the positions of elements that are changing
most rapidly, which in the case of string lists would be the characters within each string.
However, this is not the case. The first subscript is used to select a particular string out
of the list, and the second subscript may be used to identify letters within strings. This is
done because each string can have a different number of letters, and because most references to
elements within a string list are in fact references to whole strings and it is a nuisance to
have always to remember to skip past the first subscript.
For example, if you declare and load a string list variable FLIST as:
declare string list flist
flist = {
filename1
filename2
...etc.
filenameN
}
Then the values: Correspond to:
flist(0) the first string in the list
flist(3:6) the 4th through 7th strings
flist(1,3) the 4th letter in the 2nd string
flist(,0:5) the first 6 characters of every string
Illegal Subscript Values
If you specify a subscript value that is out of range, it is clipped to
the nearest legal value. Values less than zero are clipped to zero, and
values greater than or equal to the number of elements are clipped to the
number of elements - 1.