Finds locations of an identifier within a pointer, or a string within a factor or text, or a number within any numerical data structure.
Options
CASE = string token |
Whether to treat the case of letters (small or capital) as significant when searching for a string (significant, ignored); default sign |
|---|---|
TOLERANCE = scalar |
Tolerance for comparing numbers |
SUBSTITUTE = string token |
Whether to substitute dummies within pointers in DATA or FIND (yes, no); default no |
Parameters
DATA = identifiers |
Variates, scalars, matrices, tables, factors, texts or pointers to be searched |
|---|---|
FIND = scalars, texts or pointers |
Numbers, strings or identifiers to be located in DATA |
NLOCATIONS = scalars |
Saves the number of times that FIND occurs in DATA |
LOCATIONS = variates or pointers |
Saves the locations where FIND occurs as one of the values in DATA, in a variate if DATA is a one-dimensional data structure like a variate or text, or in a pointer containing a variate for each dimension if DATA is a multi-dimensional data structure like a matrix or table |
CLASSIFICATION = pointers |
Saves the classifying factors for a DATA table, in the same order as the corresponding variates in the LOCATIONS and LEVELS pointers |
LEVELS = pointers |
Saves the levels of the classifying factors where FIND occurs as one of the values of a DATA table, the information is saved in a pointer containing a variate for each factor |
Description
The 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 DATA parameter.
If 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 SUBSTITUTE=yes, 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.
Options: CASE, TOLERANCE, SUBSTITUTE.
Parameters: DATA, FIND, NLOCATIONS, LOCATIONS, CLASSIFICAION, LEVELS.
Action with RESTRICT
GETLOCATIONS takes account of restrictions on DATA variates, factors or texts.
See also
Directives: TXFIND, TXPOSITION.
Functions: GETFIRST, GETLAST, GETPOSITION, POSITION.
Commands for: Calculations and manipulation.
Example
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