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 {; 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

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.