# locate statement

The locate statement searches for the
location of a specific string expression and returns the location
in *position.var*.

## Syntax

```
locate(str.exp,dyn.array.exp{,ac.exp{,vc.exp}}
{,start.exp};position.var{;sequence.exp})[then|else statement.block]
locate str.exp in dyn.array.exp{< ac.exp{,vc.exp}>} {,start.exp} {by sequence.exp}
setting position.var[then|else statement.block]
```

## Parameter(s)

| str.exp | String expression to locate. It must match the element exactly in order for the location to be returned. |
| --- | --- |
| array.exp | Array used to search for the string expression. |
| ac.exp | Attribute used to search for the string expression. |
| vc.exp | Subvalue used to search for the string expression. |
| start.exp | Specifies the first field to search. If not specified, the entire string is searched. If ac.exp and vc.exp are both specified, start.exp is the first subvalue to search. If only ac.exp is specified, start.exp is the first value to search. If ac.exp is not specified, start.exp is the first attribute to search. |
| sequence.exp | Specifies that the elements of dyn.array.exp as being in ascending or descending ASCII sequence, and sorted with either right or left justification. Possible values are: |
| al | Ascending, left-aligned. |
| als | Ascending, left-aligned (Compatibility with the al parameter of the sort() function). |
| ar | Ascending, right-aligned. |
| ars | Ascending, right-aligned (Compatibility with the ar parameter of the sort() function). |
| dl | Descending, left-aligned. |
| dls | Descending, left-aligned (Compatibility with the dl parameter of the sort() function). |
| dr | Descending, right-aligned. |
| drs | Descending, right-aligned (Compatibility with the dr parameter of the sort() function). |
| 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, position.var defaults to the end of the string expression. If the string is not found, the position where it should be placed is returned. The s character of the sequence expression is not supported in flash compiled programs. Note: In D3, the single quotation marks around the sequence expression are no longer required.Note: Non-integers and mixed numeric and non-numeric data types may return unexpected results. | |
| position.var | Variable where the location of the string expression is returned. |

## Description

The use of the optional attribute
count expression and value count expression indicates whether the
value returned into *position.var* is a value count
or a subvalue count. If both are omitted, the value returned into *position.var* is an attribute count.

To use the start
expression while not specifying the ac expression and vc expression,
a 0 must be substituted to hold the syntactical position.

Note: The FlashBASIC or BASIC compiler does 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 must be substituted to hold the syntactical
position.

A frequent mistake when using locate is specifying one too many dynamic array specifiers. For example,
users wishing to search through a set of attributes should use `locate *str.exp* in *dyn.array*...`, not *dyn.array*. Users wishing
to search through a list of values in attribute 1 should use `locate *str.exp* in *dyn.array*...,`, not `dyn.array`.

## Example(s)

```
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
```
or

```
equ vm to char(253)
continents = ’africa’:vm:’asia’:vm:’south america’
input acontinent
locate acontinent in continents<1> by ’al’ setting position 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-aligned).

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 `]` represents a value mark.

## See also

- [Array references](https://d3codex.com/pickbasic-flashbasic/array-references/)
- [Array variable](https://d3codex.com/pickbasic-flashbasic/array-variable/)
- [Attribute count expression](https://d3codex.com/pickbasic-flashbasic/attribute-count-expression/)
- [delete() function](https://d3codex.com/pickbasic-flashbasic/delete-function/)
- [extract() function](https://d3codex.com/pickbasic-flashbasic/extract-function/)
- [ins statement](https://d3codex.com/pickbasic-flashbasic/ins-statement/)
- [insert() function](https://d3codex.com/pickbasic-flashbasic/insert-function/)
- [Numeric expressions](https://d3codex.com/pickbasic-flashbasic/numeric-expressions/)
- [ereplace() function](https://d3codex.com/pickbasic-flashbasic/ereplace-function/)
- [setting clause](https://d3codex.com/pickbasic-flashbasic/setting-clause/)
- [sort() function](https://d3codex.com/pickbasic-flashbasic/sort-function/)
- [statement blocks](https://d3codex.com/pickbasic-flashbasic/statement-blocks/)
- [Statements and functions](https://d3codex.com/pickbasic-flashbasic/statements-and-functions/)
- [Subvalue count expressions](https://d3codex.com/pickbasic-flashbasic/subvalue-count-expressions/)
- [then/else statement blocks](https://d3codex.com/pickbasic-flashbasic/then-else-statement-blocks/)
- [u1072 user exit](https://d3codex.com/pickbasic-flashbasic/u1072-user-exit/)
- [Value count expression](https://d3codex.com/pickbasic-flashbasic/value-count-expression/)

---
Source: https://d3codex.com/pickbasic-flashbasic/locate-statement/ - part of the D3Codex reference.