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