#### Array Locator Methods

Locator methods iterate over the array elements, which are then used to evaluate the expression specified by the **with **clause. The iterator argument optionally specifies the name of the variable used by the **with **expression to designate the element of the array at each iteration. If it is not specified, the name item is used by default. The scope for the iterator name is the **with **expression.

The following locator methods are supported (the **with **clause is mandatory) :

**find()**: returns all the elements satisfying the given expression**find_index()**: returns the indexes of all the elements satisfying the given expression**find_first()**: returns the first element satisfying the given expression**find_first_index()**: returns the index of the first element satisfying the given expression**find_last()**: returns the last element satisfying the given expression**find_last_index()**: returns the index of the last element satisfying the given expression

For the following locator methods, the **with **clause (and its expression) can be omitted if the relational operators (<, >, ==) are defined for the element type of the given array. If a **with **clause is specified, the relational operators (<, >, ==) must be defined for the type of the expression.

**min()**: returns the element with the minimum value or whose expression evaluates to a minimum**max()**: returns the element with the maximum value or whose expression evaluates to a maximum**unique**(): returns all elements with unique values or whose expression is unique**unique_index()**: returns the indexes of all elements with unique values or whose expression is unique

Examples:

**string **SA[10], qs[$];

**int **IA[*], qi[$];

// Find all items greater than 5

qi = IA.find( x ) with ( x > 5 );

// Find indexes of all items equal to 3

qi = IA.find_index with ( item == 3 );

// Find the first item equal to Bob

qs = SA.find_first with ( item == "Bob" );

// Find the last item equal to Henry

qs = SA.find_last( y ) with ( y == "Henry" );

// Find the index of the last item greater than Z

qi = SA.find_last_index( s ) with ( s > "Z" );

// Find the smallest item

qi = IA.min;

// Find the string with a largest numerical value

qs = SA.max **with **( item.atoi );

// Find all unique strings elements

qs = SA.unique;

// Find all unique strings in lower-case

qs = SA.**unique**( s ) **with **( s.tolower );

**Array ordering methods**

Array ordering methods can reorder the elements of one-dimensional arrays or queues.

The general prototype for the ordering methods is:

**function void **ordering_method ( array_type iterator = item )

The following ordering methods are supported:

**reverse()**: reverses all the elements of the array (packed or unpacked). Specifying a**with**clause shall be a compiler error.

**sort()**: sorts the unpacked array in ascending order, optionally using the expression in the**with**clause.

The **with **clause (and its expression) is optional when the relational operators are defined for the array element type.

**rsort()**: sorts the unpacked array in descending order, optionally using the expression in the**with**clause.

The **with **clause (and its expression) is optional when the relational operators are defined for the array element type.

**shuffle()**: randomizes the order of the elements in the array. Specifying a**with**clause shall be a compiler error.

Examples:

**string **s[] = { "hello", "good", "morning" };

s.reverse; // s becomes { "morning", "good", "hello" };

**logic **[4:1] a = 4’bXZ01;

a.reverse; // a becomes 4’b10ZX

**int **q[$] = { 4, 5, 3, 1 };

q.sort; // q becomes { 1, 3, 4, 5 }

**struct **{ byte red, green, blue } c [512];

c.sort **with **( item.red ); // sort c using the red field only

c.sort( x ) **with **( x.blue << 8 + x.green ); // sort by blue then green

**Array reduction methods**

Array reduction methods can be applied to any unpacked array to reduce the array to a single value. The expression within the optional **with **clause can be used to specify the item to use in the reduction.

The prototype for these methods is:

**function **expression_or_array_type reduction_method (array_type iterator = item)

The method returns a single value of the same type as the array element type or, if specified, the type of the expression in the **with **clause. The **with **clause can be omitted if the corresponding arithmetic or boolean reduction operation is defined for the array element type. If a **with **clause is specified, the corresponding arithmetic or boolean reduction operation must be defined for the type of the expression.

The following reduction methods are supported:

**sum()**: returns the sum of all the array elements, or if a**with**clause is specified, returns the sum of the values yielded by evaluating the expression for each array element.**product():**returns the product of all the array elements, or if a**with**clause is specified, returns the product of the values yielded by evaluating the expression for each array element.**and()**: returns the bit-wise AND ( & ) of all the array elements, or if a**with**clause is specified, returns the bit-wise AND of the values yielded by evaluating the expression for each array element**or()**: returns the bit-wise OR ( | ) of all the array elements, or if a**with**clause is specified, returns the bitwise OR of the values yielded by evaluating the expression for each array element**xor()**: returns the logical XOR ( ^ ) of all the array elements, or if a**with**clause is specified, returns the XOR of the values yielded by evaluating the expression for each array element.

Examples:

**byte **b[] = { 1, 2, 3, 4 };

**int **y;

y = b.sum ; // y becomes 10 => 1 + 2 + 3 + 4

y = b.product ; // y becomes 24 => 1 * 2 * 3 * 4

y = b.**xor with **( item + 4 ); // y becomes 12 => 5 ^ 6 ^ 7 ^ 8

**Iterator index querying**

The expressions used by array manipulation methods sometimes need the actual array indexes at each iteration, not just the array element. The index method of an iterator returns the index value of the specified dimension.

The prototype of the index method is:

**function **int_or_index_type index ( **int **dimension = 1 )

The slowest variation is dimension 1. Successively faster varying dimensions have sequentially higher dimension numbers. If the dimension is not specified, the first dimension is used by default. The return type of the index method is an **int **for all array iterator items except associative arrays, which returns an index of the same type as the associative index type.

For example:

**int **arr[]

**int **mem[9:0][9:0], mem2[9:0][9:0];

**int **q[$];

//Finds all items equal to their position (index)

q = arr.find **with **( item == item.index );

//Finds all items in mem that are greater than the corresponding item in mem2

q = mem.find( x ) **with **( x > mem2[x.index(1)][x.index(2)] );