BASICBASIC statementslocate statement

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<1>. Users wishing to search through a list of values in attribute 1 should use locate str.exp in dyn.array<1>...,, not dyn.array<1,1>.

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, Array variable, Attribute count expression, delete() function, extract() function, ins statement, insert() function, Numeric expressions, ereplace() function, setting clause, sort() function, statement blocks, Statements and functions, Subvalue count expressions, then/else statement blocks, u1072 user exit, Value count expression

Parent topic: BASIC statements