The new storage class GRIDMAP is a two-dimensional variation of ORDMAP with a two-part key (row and column), suitable for handling datasets consisting of rows and columns.
Declaration
dimx $map, gridmap(int; varstr; varstr) ! num row, str col, str value
dimx $map, gridmap(int; int; varstr) ! num row and col, str value
Assignment
$map(row, col) = value
Depending on how the gridmap $map was declared, the col specification should be a string (representing the column title) or a number (column number). In all cases, the row is numeric. Maximum range for the row number index is -9,999,999 to 99,999,999. Maximum range for the col number index is -9,999 to 99,999. (There is no maximum range for the string version of the column index.)
Gridmap dot functions
The gridmap supports two new functions .minrow() and .maxrow(), plus an expanded form of the .key() function:
.minrow($map()) - returns first row number
.maxrow($map()) - returns last row number
.key($$i,1) - returns the 1st index (row) for specified iterator
.key($$i,2) - returns the 2nd index (col) for specified iterator
The standard .key() and .extent() functions work on gridmaps as follows:
.key($$i) - concatenated key formatted as ########|#####
.extent($map()) - number of row,col,value triplets in entire structure
Note that the minimum row number is not necessarily one, nor is the maximum row number necessarily the same as the number of rows. There is no special function to return the extent (number of) rows or columns independently.
Gridmap Iteration
Iterate through the gridmap using either a foreach loop (as with ordmap) or a traditional for/next loop (for the numeric dimensions). In the foreach case, iteration proceeds across the columns and down the rows. Use the expanded .key() dot function to determine the row and column associated with the current iterator value, as in this example which iterates through the entire gridmap, display the row and column indices along with the value:
foreach $$i in $map()
? "Row "; .key($$i,1); ", Col "; .key($$i,2); "-->"; $$i
next $$i
A standard numeric for/next loop can be used to iterate through the rows, and in the case of the gridmap with numeric columns, through the columns as well. Note that you can use the .minrow() and .maxrow() functions to get the starting and ending row values, but there is no guarantee that all of the intervening rows exist. And in the case of the columns, there is no mechanism to determine the extent or range of columns for each rows, other than .isnull(). The following example iterates through all the rows and columns one through five, skipping any unassigned elements:
for row = .minrow($map()) to .maxrow($map())
for col = 1 to 5 ! gridmap(int; int; varstr)
if not .isnull($map(row,col)) then ! if row,col,value triplet exists...
...
endif
next col
next row
