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 greenArray 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 ^ 8Iterator 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)] );