| LN | Index Level | LOCK |
| Syntax |
LOCATE(string.expression, dynamic.array.expression {, ac.expression{, vc.expression{, start.expression}}}; position.variable {; sequence.expression}) [THEN | ELSE statement.block]
LOCATE string.expression IN dynamic.array.expression{ <ac.expression{, vc.expression}>} {,start.expression} {BY sequence.expression} SETTING position.variable [THEN | ELSE statement.block] |
| Category | BASIC |
| Type | Statement |
| Description |
searches for the location of a specific "string.expression" and returns the location in "position.variable" of where the string was found or if the string wasn't found, the position that it should be placed.
The elements of "dynamic.array.expression" may be specified as being in ascending or descending ASCII sequence, and sorted with either right or left justification. Sequence parameters: (In D3, the single quotes around the sequence parameters are no longer required.) al Ascending, left-justified. ar Ascending, right-justified. dl Descending, left-justified. dr Descending, right-justified. If the first character in the "sequence" expression is anything except "a" or "d", or the "l" or "r" is not specified, no sort is performed. If the second character is anything except "r", left justification is assumed. If no "sequence" parameter is specified, the "position.variable" position defaults to the end of the string.expression. The use of the optional "ac.expression" and "vc.expression" indicates whether the value returned into "position.variable" is a value count or a subvalue count. If both are omitted, the value returned into "position.variable" is an attribute count. "start.expression" is the first field to search. If not specified, the entire string is searched. If "ac.expression" and "vc.expression" are both specified, "start.expression" is the first subvalue to search. If only "ac.expression" is specified, "start.expression" is the first value to search. If "ac.expression" is not specified, "start.expression" is the first attribute to search. The "string.expression" must match the element exactly in order for the location to be returned. To use the "start.expression" while not specifying the "ac.expression" and "vc.expression", a "0" (zero) must be substituted to hold the syntactical position. See the "then/else construct" for an explanation on the use of "then" and "else" clauses in statements that allow or require them. |
| Options | |
| See Also | statements & functions num.expression array references DELETE ac.expression string.expression THEN | ELSE statement.block statement.block REPLACE INSERT vc.expression INS EXTRACT array.variable u1072 SETTING sc.expression SORT |
| Example |
equ vm to char(253)
continents = 'africa':vm:'asia':vm:'south america' input acontinent locate(acontinent,continents,1;position;'al') then crt acontinent:' is already there' end else continents=insert(continents,1,position;acontinent) end crt continents "continents" is a list of continents in alphabetical order. "acontinent" is added to the list only if it does not already exist. The "locate" statement uses the sequence parameter "al", ascending, left-justified. If the value of "acontinent" is "europe", it does not exist in "continents", causing "locate' to take the "else" clause with the value of "position" set to 3. The "insert" function places "europe" in front of "south america" leaving "continents" as: africa]asia]europe]south america The bracket ( ] ) represents a value mark. |
| Warnings |
The FlashBASIC compiler will not accept a null (represented by two successive commas) for the "vc.expression" or "ac.expression". To use the "start.expression" while not specifying the "ac.expression" and "vc.expression", a "0" (zero) must be substituted to hold the syntactical position.
Release 5.2 and below - Right justified sorting worked more like Access's right justified sort. Release 6.0 - Right justified sorting is 100% compatible with that displayed by R83 which is a left-to-right ASCII sort on a list that has been right-justified. The release 5.2 and below version may be invoked IN THE D3 RELEASE 6.0 level ONLY by using the "ars" or "drs" options. The FlashBASIC compiler does not support the "s" option. Release 6.1 and higher - Right justified sorting is R83 compatible. No other options are supported. A frequent mistake when using locate is to specify one two many dynamic array specifiers. For example, a user wishing to search through a set of attributes should use "locate string in dynamic.array...," NOT "dynamic.array<1>." A user wishing to search through a list of values in attribute one should use "locate string in dynamic.array<1>...," NOT "dynamic.array<1,1>." |
| Compatibility | D3 7.0 R83 AP AP 6.0 AP 6.1 |
| LN | Index Level | LOCK |