Array Manipulation Methods in SystemVerilog with example

SV provides build in methods to facilitate searching from array, array ordering and reduction.

Array locator methods:

Array locator methods operate on any unpacked array, including queues, but their return type is a queue.

Element locator methods (with clause is mandatory):

find() returns all the elements satisfying the given expression.

find_first() returns the first element satisfying the given expression.

find_last() returns the last element satisfying the given expression.

Index locator methods (with clause is mandatory):

find_index() returns the indices of all the elements satisfying the given expression.

find_first_index() returns the index of the first element satisfying the given expression.

find_last_index() returns the index of the last element satisfying the given expression.

Index locator methods return a queue of int for all arrays except associative arrays, which return a queue of the same type as the associative index type.

arrays that specify a wildcard index type shall not be allowed.

If no elements satisfy the given expression or the array is empty (in the case of a queue or dynamic array), then an empty queue is returned.

Index locator methods return a queue with the indices of all items that satisfy the expression.

The optional expression specified by the with clause shall evaluate to a Boolean value.

Let's go through below example,

---------------------------------------------------------------------

	module top();
	int q[$];
	int result[$];
	initial begin
	q = {9, 1, 8, 3, 4, 4};
	$display("1. queue 'q' in decimal : %p", q);
	// Find all the elements less than 5
	$display("2. find with (item < 5) : %p", q.find with (item < 5) ); // These
	$display("3. find() with (item < 5) : %p", q.find() with (item < 5) ); // All
	$display("4. find(item) with (item < 5) : %p", q.find(item) with (item < 5) ); // Are
	$display("5. find(x) with (x < 5) : %p", q.find(x) with (x < 5) ); // Equivalent
	// Find all the elements greater than 3
	result = q.find with (item > 3);
	$display("6. find with (item > 3) : %p", result);
	// Find indices of all items greater than 7
	result = q.find_index with (item > 7);
	$display("7. find_index with (item > 7) : %p", result);
	// Find indices of all items equals to 4
	$display("8. find_index with (item == 4) : %p", q.find_index with (item == 4) );
	// Find first item grater than 8
	result = q.find_first with (item > 8);
	$display("9. find_first with (item > 8) : %p", result);
	// Find first item grater than 10
	$display("10. find_first with (item > 10) : %p", q.find_first with (item > 10) );
	// Find index of first item equals to 4
	result = q.find_first_index with (item == 4);
	$display("11. find_first_index with (item == 4) : %p", result);
	// Find last item less than 4
	$display("12. find_last with (item < 4) : %p", q.find_last with (item < 4) );
	// Find index of last item equals to 4
	$display("13. find_last_index with (item == 4) : %p", q.find_last_index with (item == 4));
	// find all items equal to their position (index)
	//result = q.find with ( item == item.index );
	//$display("14. find with ( item == item.index ) : %p", result);
	end
	endmodule : top
	//Output:
	// 1. queue 'q' in decimal : '{9, 1, 8, 3, 4, 4}
	// 2. find with (item < 5) : '{1, 3, 4, 4}
	// 3. find() with (item < 5) : '{1, 3, 4, 4}
	// 4. find(item) with (item < 5) : '{1, 3, 4, 4}
	// 5. find(x) with (x < 5) : '{1, 3, 4, 4}
	// 6. find with (item > 3) : '{9, 8, 4, 4}
	// 7. find_index with (item > 7) : '{0, 2}
	// 8. find_index with (item == 4) : '{4, 5}
	// 9. find_first with (item > 8) : '{9}
	// 10. find_first with (item > 10) : '{}
	// 11. find_first_index with (item == 4) : '{4}
	// 12. find_last with (item < 4) : '{3}
	// 13. find_last_index with (item == 4) : '{5}

view raw array_find_methods.sv hosted with ❤ by GitHub

---------------------------------------------------------------------

Element locator methods (with clause is optional):

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 evaluates to a unique value.

unique_index() returns the indices of all elements with unique values or whose expression evaluates to a unique value.

Let's go through below example,

---------------------------------------------------------------------

	module top();
	int q[$];
	int result[$];
	initial begin
	q = {2, 6, 7, 3, 2, 7, 10, 3, 16};
	$display("1. queue 'q' in decimal : %p", q);
	result = q.min();
	$display("2. Minimum element of queue 'q' : %p", result);
	//result.delete();
	//result = q.min with (item > 5);
	//$display("3. Minimum element of queue 'q' : %p", result);
	result = q.max();
	$display("4. Maximum element of queue 'q' : %p", result);
	//result.delete();
	//result = q.max(x) with (x <15);
	//$display("5. Maximum element of queue 'q' : %p", result);
	result = q.unique();
	$display("6. Unique elements of queue 'q' : %p", result);
	result = q.unique_index();
	$display("7. Index of Unique elements of queue 'q' : %p", result);
	end
	endmodule : top
	//Output:
	// 1. queue 'q' in decimal : '{2, 6, 7, 3, 2, 7, 10, 3, 16}
	// 2. Minimum element of queue 'q' : '{2}
	// 4. Maximum element of queue 'q' : '{16}
	// 6. Unique elements of queue 'q' : '{2, 6, 7, 3, 10, 16}
	// 7. Index of Unique elements of queue 'q' : '{0, 1, 2, 3, 6, 8}

view raw other_locator_methods.sv hosted with ❤ by GitHub

---------------------------------------------------------------------

Array reduction methods:

Array reduction methods may be applied to any unpacked array of integral values to reduce the array to a single value

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 bitwise AND ( & ) of all the array elements or, if a with clause is specified, returns the bitwise AND of the values yielded by evaluating the expression for each array element.

or() returns the bitwise 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 bitwise XOR ( ^ ) of all the array elements or, if a with clause is specified, returns the bitwise XOR of the values yielded by evaluating the expression for each array element.

Let's go through below example,

---------------------------------------------------------------------

	module top();
	int unsigned q[$];
	int unsigned result;
	initial begin
	q = {1, 2, 3, 4};
	$display("1. queue 'q' in decimal : %p", q);
	result = q.sum(); // 1 + 2 + 3 + 4 = 10
	$display("2. sum of all elements of queue 'q' : %0d", result);
	result = q.product(); // 1 * 2 * 3 * 4 = 24
	$display("3. product of all elements of queue 'q' : %0d", result);
	$display("");
	q = {4, 5, 'hC, 'hF};
	$display("4. queue 'q' in decimal : %p", q);
	result = q.and(); // 0b0100 & 0b0101 & 0b1100 & 0b1111 = 0b0100 = 4
	$display("5. AND of all elements of queue 'q' : %0d", result);
	$display("");
	q = {4, 5, 8, 0};
	$display("6. queue 'q' in decimal : %p", q);
	result = q.or(); // 0b0100 | 0b0101 | 0b1000 | 0b0000 = 0b1101 = 13
	$display("7. OR of all elements of queue 'q' : %0d", result);
	$display("");
	q = {1, 2, 3, 4};
	$display("8. queue 'q' in decimal : %p", q);
	result = q.xor(); // 0b0001 ^ 0b0010 ^ 0b0011 ^ 0b0100 = 0b0100 = 4
	$display("9. XOR of all elements of queue 'q' : %0d", result);
	result = q.xor() with (item + 4); // 0b0101 ^ 0b0100 ^ 0b0111 ^ 0b1000 = 0b1100 = 12
	$display("10. XOR (with clause) of all elements of queue 'q' : %0d", result);
	end
	endmodule : top
	//Output:
	// 1. queue 'q' in decimal : '{1, 2, 3, 4}
	// 2. sum of all elements of queue 'q' : 10
	// 3. product of all elements of queue 'q' : 24
	//
	// 4. queue 'q' in decimal : '{4, 5, 12, 15}
	// 5. AND of all elements of queue 'q' : 4
	//
	// 6. queue 'q' in decimal : '{4, 5, 8, 0}
	// 7. OR of all elements of queue 'q' : 13
	//
	// 8. queue 'q' in decimal : '{1, 2, 3, 4}
	// 9. XOR of all elements of queue 'q' : 4
	// 10. XOR (with clause) of all elements of queue 'q' : 12

view raw array_reduction_methods.sv hosted with ❤ by GitHub

---------------------------------------------------------------------

Array ordering methods:

Array ordering methods reorder the elements of any unpacked array (fixed or dynamically sized) except for associative arrays.

reverse() reverses the order of the elements in the array. Specifying a with clause shall be a compiler error.

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

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

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

Let's go through below example,

---------------------------------------------------------------------

	module top();
	int unsigned q[$];
	initial begin
	q = {9, 1, 8, 3, 4, 4};
	$display("1. queue 'q' in decimal : %p", q);
	q.reverse();
	$display("2. After calling reverse() function, queue 'q' in decimal : %p", q);
	q.sort();
	$display("3. After calling sort() function, queue 'q' in decimal : %p", q);
	// First ODD and then EVEN in assending order
	q.sort with (item % 2 == 0);
	$display("4. After calling sort() function, queue 'q' in decimal : %p", q);
	// First EVEN and then ODD in assending order
	q.sort with (item % 2 != 0);
	$display("5. After calling sort() function, queue 'q' in decimal : %p", q);
	q.rsort();
	$display("6. After calling rsort() function, queue 'q' in decimal : %p", q);
	q.shuffle();
	$display("7. After calling shuffle() function, queue 'q' in decimal : %p", q);
	end
	endmodule : top
	//Output:
	// 1. queue 'q' in decimal : '{9, 1, 8, 3, 4, 4}
	// 2. After calling reverse() function, queue 'q' in decimal : '{4, 4, 3, 8, 1, 9}
	// 3. After calling sort() function, queue 'q' in decimal : '{1, 3, 4, 4, 8, 9}
	// 4. After calling sort() function, queue 'q' in decimal : '{1, 3, 9, 4, 4, 8}
	// 5. After calling sort() function, queue 'q' in decimal : '{4, 4, 8, 1, 3, 9}
	// 6. After calling rsort() function, queue 'q' in decimal : '{9, 8, 4, 4, 3, 1}
	// 7. After calling shuffle() function, queue 'q' in decimal : '{4, 4, 8, 1, 9, 3}

view raw array_ordering_methods.sv hosted with ❤ by GitHub

---------------------------------------------------------------------

Now let's see couple of practical examples, let's say we want to find number of 1s from bit array or bit queue or we want to find out number of non-zero elements in any array or queue.

---------------------------------------------------------------------

	module top();
	int unsigned q[$];
	int unsigned r[$];
	bit bitq[$];
	int unsigned result;
	initial begin
	q = {1, 0, 2, 3, 0, 4};
	bitq = {0 ,1, 1, 1, 0, 0, 1, 0, 0, 0, 1, 0, 1, 1};
	$display("1. queue 'q' in decimal : %p", q);
	$display("2. queue 'bitq' : %p", bitq);
	result = bitq.sum(item) with (int'(item));
	$display("3. Number of 1's in 'bitq' : %0d", result);
	r = q.find(x) with (x != 0);
	$display("4. Number of non-zero elements in queue 'q' :%0d", r.size());
	end
	endmodule : top
	//Output:
	// 1. queue 'q' in decimal : '{1, 0, 2, 3, 0, 4}
	// 2. queue 'bitq' : '{'h0, 'h1, 'h1, 'h1, 'h0, 'h0, 'h1, 'h0, 'h0, 'h0, 'h1, 'h0, 'h1, 'h1}
	// 3. Number of 1's in 'bitq' : 7
	// 4. Number of non-zero elements in queue 'q' :4

view raw array_methods_examples.sv hosted with ❤ by GitHub

---------------------------------------------------------------------