Finds locations of an identifier within a pointer, or a string within a factor or text, or a number within any numerical data structure.
||Whether to treat the case of letters (small or capital) as significant when searching for a string (
||Tolerance for comparing numbers|
||Whether to substitute dummies within pointers in
||Variates, scalars, matrices, tables, factors, texts or pointers to be searched|
||Numbers, strings or identifiers to be located in
||Saves the number of times that
||Saves the locations where
||Saves the classifying factors for a
||Saves the levels of the classifying factors where
GETLOCATIONS directive finds where a particular item occurs as one of the values stored by a Genstat data structure. So, for example, it can locate the lines within a text structure that are equal to a particular string, or it can locate the rows and columns of a matrix that hold a particular number, or it can locate the numbers of the suffixes where a pointer contains a particular identifier.
The item to find is specified by the
FIND parameter, as a scalar (for a number), or a single-valued text (for a string of characters), or a single-valued pointer (for the identifier of a data structure). The data structure to search is supplied by the
FIND pointer contains a dummy,
GETLOCATIONS usually looks to see that dummy is contained in the
DATA pointer. Alternatively, if you set option
SUBSTITUTE=yes and the
FIND pointer contains a dummy, it is replaced by the data structure to which it points. Then if that data structure is a dummy, it too is replaced, amd so on until we reach a data structure that is not a dummy. However, if the original dummy (or any of the dummies to which it points) is unset, the original dummy is retained. The same substitution is done on any dummies in the
DATA pointer. So, when
GETLOCATIONS matches the structures to which the dummies (eventually) point, rather than the dummies themselves.
The number of times that
FIND occurs in
DATA can be saved, in a scalar, by the
NLOCATIONS parameter. The locations where
FIND occurs can be saved by the
LOCATIONS parameter. These are saved in a variate if
DATA is a one-dimensional structure i.e. a scalar, variate, text, factor or pointer. If
DATA is a rectangular, diagonal or symmetric matrix, they are saved in a pointer containing two variates. The first saves the row locations, and the second saves the column locations. If
DATA is a table,
LOCATIONS saves a pointer with a variate for each factor classifying the table. Each variate stores the locations within the dimension classified by a particular factor. So, for example, with a two-way
DATA table the first variate stores the row numbers, and the second variate stores the column numbers. The
CLASSIFICATION parameter can save the factors in the same order as the
LOCATIONS variates, in case you are unsure of which factor corresponds to each dimension. The
LEVELS parameter provides an alternative to
LOCATIONS for tables, storing the factor levels corresponding to the positions in each dimension, rather than the numbers of e.g. the rows or columns. If a
DATA table has margins and the number to
FIND occurs in one of them, a missing value will be stored for the corresponding location or level.
GETLOCATIONS takes account of restrictions on
DATA variates, factors or texts.
Commands for: Calculations and manipulation.
CAPTION 'GETLOCATIONS examples'; STYLE=meta " factors " FACTOR [LEVELS=!(0.1,0.2,0.3); VALUES=0.1,0.2,0.3] f GETLOCATIONS DATA=f; FIND=0.2; NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc FACTOR [LEVELS=3; LABELS=!t(a,bcb,c); VALUES=1,2,3,2,1] f GETLOCATIONS DATA=f; FIND=!t(bcb); NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc " matrices " MATRIX [ROWS=3; COLUMNS=4; VALUES=1...5,2.01,7,8...11,2] rm PRINT rm GETLOCATIONS DATA=rm; FIND=2; NLOCATIONS=nloc; LOCATIONS=mloc PRINT nloc,mloc; FIELD=8 GETLOCATIONS [TOLERANCE=0.1] DATA=rm; FIND=2; NLOCATIONS=nloc; LOCATIONS=mloc PRINT nloc,mloc; FIELD=8 " pointers " GETLOCATIONS DATA=!p(a,b,c); FIND=!p(b); NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc GETLOCATIONS DATA=!p(a,b,c,b,d,e); FIND=!p(b); NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc " texts " GETLOCATIONS DATA=!t(aa,bcb,ccc); FIND=!t(bcb); NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc GETLOCATIONS [CASE=ignored] DATA=!t(aa,Bcb,ccc,bcB,dd,eee); FIND=!t(bCb);\ NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc " variates " VARIATE [VALUES=0.1,0.2,0.3] v GETLOCATIONS DATA=v; FIND=0.2; NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc VARIATE [VALUES=0.1,0.2,0.3,0.2,0.1] v GETLOCATIONS DATA=v; FIND=0.2; NLOCATIONS=nloc; LOCATIONS=loc PRINT nloc,loc