Tutorials

Learn More

Array manipulation methods

SystemVerilog provides built-in methods for array reduction, ordering, locator, iterator index querying.

In array manipulation methods, it iterates over array elements and evaluates the expression using the ‘with’ clause

‘with’ clause

The expression to be evaluated when iterating over the array elements can be specified using the ‘with’ clause. The iterator argument can be specified with some local variable which is used to refer to the current element of an array in the expression. However, it is not mandatory to use a local variable and if it is not used then the ‘item’ keyword is referred as a by-default keyword.

Example:

Here, color is a class variable of an enum type. The below example shows how to use the find method with and without a local variable.

//With local variable 
arr.find(x) with (x.color == YELLOW);

//Without local variable
arr.find with (item.color == YELLOW);

Array Locator methods

Array locator methods operate on queues, unpacked arrays, but their return type is a queue. An array locator methods do below operations

  1. Search an index or elements of the array
  2. Array traversal in an unspecified order

The array location methods can be classified into two types

  1. Element locator
  2. Index locator

Element locator

In element locator type, locator methods iterate over all elements in an array, and then it is used to evaluate the expression specified ‘with’ clause and returns element/s in a queue. For some of the methods, the ‘with’ clause is optional.

Element locator methods

Methods

Description

find

Returns all 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.

unique

Returns all elements with unique values or whose expression is unique 

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.

Element locator Example

An associative array of type transaction class and a fixed array are used to demonstrate how the above methods work.

Element array locator module
typedef enum {RED, GREEN, YELLOW} color_type;
class transaction;
  rand bit [2:0] addr;
  rand bit [2:0] data;
  rand color_type colors; 
  
  function void print;
    $display("addr = %0d, data = %0d and color = %s", addr, data, colors.name);
  endfunction
endclass

module elememt_arr_locator_ex;
  transaction tr;
  transaction tr_assoc_arr[int];
  int arr[8] = '{5,6,9,2,3,4,6,10};
  
  initial begin
    $display("-------------------------------------");
    $display("--------- Generating array ----------");
    $display("-------------------------------------");
    array_gen();
    $display("-------------------------------------");
    $display("------------- find method -----------");
    $display("-------------------------------------");
    find_method();
    $display("-------------------------------------");
    $display("--------- find_first method ---------");
    $display("-------------------------------------");
    find_first_method();
    $display("-------------------------------------");
    $display("--------- find_last method ----------");
    $display("-------------------------------------");
    find_last_method();
    $display("-------------------------------------");
    $display("---------- unique method ------------");
    $display("-------------------------------------");
    unique_method();
    $display("-------------------------------------");
    $display("---------- min max method -----------");
    $display("-------------------------------------");
    min_max_method();
  end
endmodule
Generate associative array
function void array_gen();
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[3] =  tr;

  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[5] =  tr;
  
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[8] =  tr;
    
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[11] =  tr;
endfunction
Corresponding output:
-------------------------------------
--------- Generating array ----------
-------------------------------------
addr = 1, data = 7 and color = RED
addr = 2, data = 7 and color = RED
addr = 4, data = 3 and color = RED
addr = 2, data = 3 and color = GREEN
addr = 5, data = 2 and color = YELLOW
find method
function void find_method();
  transaction tr_q[$], tr;
  int qsize;
    
  // Find all elements having item as YELLOW color
  tr_q = tr_assoc_arr.find with (item.colors == YELLOW);
  qsize = tr_q.size;
  $display("Number of elements for color item 'YELLOW' = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
    
  // expression has multiple conditions
  tr_q = tr_assoc_arr.find with (item.data >= 1 && item.data <= 5);
  qsize = tr_q.size;
  $display("\nNumber of elements for data item in range of 1 to 5 = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
endfunction
Corresponding output:
-------------------------------------
------------- find method -----------
-------------------------------------
Number of elements for color item 'YELLOW' = 1
Element 1: 
addr = 5, data = 2 and color = YELLOW

Number of elements for data item in range of 1 to 5 = 3
Element 1: 
addr = 4, data = 3 and color = RED
Element 2: 
addr = 2, data = 3 and color = GREEN
Element 3: 
addr = 5, data = 2 and color = YELLOW
find_first method
function void find_first_method();
  transaction tr_q[$], tr;
  int qsize;
    
  // Find first element having item as YELLOW color
  tr_q = tr_assoc_arr.find_first with (item.colors == YELLOW);
  qsize = tr_q.size;
  $display("Number of elements for color item 'YELLOW' = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
    
  // expression has multiple conditions
  tr_q = tr_assoc_arr.find_first with (item.data >= 1 && item.data <= 5);
  qsize = tr_q.size;
  $display("\nNumber of elements for data item in range of 1 to 5 = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
endfunction
Corresponding output:
-------------------------------------
--------- find_first method ---------
-------------------------------------
Number of elements for color item 'YELLOW' = 1
Element 1: 
addr = 5, data = 2 and color = YELLOW

Number of elements for data item in range of 1 to 5 = 1
Element 1: 
addr = 4, data = 3 and color = RED
find_last method
function void find_last_method();
  transaction tr_q[$], tr;
  int qsize;
    
  // Find last element having item as YELLOW color
  tr_q = tr_assoc_arr.find_last with (item.colors == YELLOW);
  qsize = tr_q.size;
  $display("Number of elements for color item 'YELLOW' = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
    
  // expression has multiple conditions
  tr_q = tr_assoc_arr.find_last with (item.data >= 1 && item.data <= 5);
  qsize = tr_q.size;
  $display("\nNumber of elements for data item in range of 1 to 5 = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
endfunction
Corresponding output:
-------------------------------------
--------- find_last method ----------
-------------------------------------
Number of elements for color item 'YELLOW' = 1
Element 1: 
addr = 5, data = 2 and color = YELLOW

Number of elements for data item in range of 1 to 5 = 1
Element 1: 
addr = 5, data = 2 and color = YELLOW
unique method
function void unique_method();
  transaction tr_q[$], tr;
  int arr_q[$];
  int qsize;
    
  arr_q = arr.unique();
  $display("unique element in arr = %p", arr_q);
    
  // Find unique elements of addr.
  tr_q = tr_assoc_arr.unique with (item.addr);
  qsize = tr_q.size;
  $display("Number of unique elements for addr = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    $display("Element %0d: ",i+1);
    tr = tr_q.pop_front();
    tr.print();
  end
endfunction
Corresponding output:
-------------------------------------
---------- unique method ------------
-------------------------------------
unique element in arr = '{5, 6, 9, 2, 3, 4, 10}
Number of unique elements for addr = 4
Element 1: 
addr = 1, data = 7 and color = RED
Element 2: 
addr = 2, data = 7 and color = RED
Element 3: 
addr = 4, data = 3 and color = RED
Element 4: 
addr = 5, data = 2 and color = YELLOW
min and max methods
function void min_max_method();
  transaction tr_q[$], tr;
  int arr_q[$];
  int qsize;
    
  // Find min and max element in an array
  arr_q = arr.min;
  $display("min element in arr = %p", arr_q);
  arr_q = arr.max;
  $display("max element in arr = %p", arr_q);
    
  tr_q = tr_assoc_arr.min with (item.addr);
  qsize = tr_q.size;
       
  for(int i = 0; i < qsize; i++) begin
    $display("Min element w.r.t. addr is ");
    tr = tr_q.pop_front();
    tr.print();
  end
    
  tr_q = tr_assoc_arr.max with (item.addr);
  qsize = tr_q.size;
       
  for(int i = 0; i < qsize; i++) begin
    $display("Max element w.r.t. addr is ");
    tr = tr_q.pop_front();
    tr.print();
  end
endfunction
Corresponding output:
-------------------------------------
---------- min max method -----------
-------------------------------------
min element in arr = '{2}
max element in arr = '{10}
Min element w.r.t. addr is 
addr = 1, data = 7 and color = RED
Max element w.r.t. addr is 
addr = 5, data = 2 and color = YELLOW
Execute complete code

Index locator

The index locator method returns index or indexes on iterating over the array.

Methods

Description

find_index

Returns the indexes of all 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

unique_index

Returns the indexes of all elements with unique values or whose expression is unique.
Index locator module
typedef enum {RED, GREEN, YELLOW} color_type;
class transaction;
  rand bit [2:0] addr;
  rand bit [2:0] data;
  rand color_type colors; 
  
  function void print;
    $display("addr = %0d, data = %0d and color = %s", addr, data, colors.name);
  endfunction
endclass

module elememt_arr_locator_ex;
  transaction tr;
  transaction tr_assoc_arr[int];
  int arr[8] = '{5,6,9,2,3,4,6,10};
  
  initial begin
    $display("-------------------------------------");
    $display("--------- Generating array ----------");
    $display("-------------------------------------");
    array_gen();
    $display("-------------------------------------");
    $display("--------- find_index method ---------");
    $display("-------------------------------------");
    find_index_method();
    $display("-------------------------------------");
    $display("------ find_first_index_method ------");
    $display("-------------------------------------");
    find_first_index_method();
    $display("-------------------------------------");
    $display("------ find_last_index method -------");
    $display("-------------------------------------");
    find_last_index_method();
    $display("-------------------------------------");
    $display("-------- unique_index method --------");
    $display("-------------------------------------");
    unique_index_method();
  end
endmodule
Generate associative array
function void array_gen();
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[3] =  tr;
    
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[5] =  tr;
    
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[8] =  tr;
    
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[11] =  tr;
    
  tr = new();
  assert(tr.randomize());
  tr.print();
  tr_assoc_arr[15] =  tr;
endfunction
Corresponding output:
-------------------------------------
--------- Generating array ----------
-------------------------------------
addr = 1, data = 7 and color = RED
addr = 2, data = 7 and color = RED
addr = 4, data = 3 and color = RED
addr = 2, data = 3 and color = GREEN
addr = 5, data = 2 and color = YELLOW
find_index method
function void find_index_method();
  int idx_q[$], idx;
  int qsize;
    
  // Find all idx having element as RED color
  idx_q = tr_assoc_arr.find_index with (item.colors == RED);
  qsize = idx_q.size;
  $display("Number of indexes having color item 'RED' = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
    
  //expression has multiple conditions
  idx_q = tr_assoc_arr.find_index with (item.data == 3 && item.colors <= RED);
  qsize = idx_q.size;
  $display("\nNumber of indexes for data == 3 and color == RED is %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
endfunction
Corresponding output:
-------------------------------------
--------- find_index method ---------
-------------------------------------
Number of indexes having color item 'RED' = 3
Element 1 for popped index = 3: 
addr = 1, data = 7 and color = RED
Element 2 for popped index = 5: 
addr = 2, data = 7 and color = RED
Element 3 for popped index = 8: 
addr = 4, data = 3 and color = RED

Number of indexes for data == 3 and color == RED is 1
Element 1 for popped index = 8: 
addr = 4, data = 3 and color = RED
find_first_index method
function void find_first_index_method();
  int idx_q[$], idx;
  int qsize;
    
  // Find first idx having element as RED color
  idx_q = tr_assoc_arr.find_first_index with (item.colors == RED);
  qsize = idx_q.size;
  $display("Number of index having color item 'RED' = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped first index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
    
  //expression has multiple conditions
  idx_q = tr_assoc_arr.find_first_index with (item.data >= 3 && item.colors <= RED);
  qsize = idx_q.size;
  $display("\nNumber of indexes for data >= 3 and color == RED is %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped first index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
endfunction
Corresponding output:
-------------------------------------
------ find_first_index method ------
-------------------------------------
Number of index having color item 'RED' = 1
Element 1 for popped first index = 3: 
addr = 1, data = 7 and color = RED

Number of indexes for data >= 3 and color == RED is 1
Element 1 for popped first index = 3: 
addr = 1, data = 7 and color = RED
find_last_index method
function void find_last_index_method();
  int idx_q[$], idx;
  int qsize;
    
  // Find all idx having element as RED color
  idx_q = tr_assoc_arr.find_last_index with (item.colors == RED);
  qsize = idx_q.size;
  $display("Number of indexes having color item 'RED' = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped last index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
    
  //expression has multiple conditions
  idx_q = tr_assoc_arr.find_last_index with (item.data >= 3 && item.colors <= RED);
  qsize = idx_q.size;
  $display("\nNumber of indexes for data >= 3 and color == RED is %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped last index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
endfunction
Corresponding output:
-------------------------------------
------ find_last_index method -------
-------------------------------------
Number of indexes having color item 'RED' = 1
Element 1 for popped last index = 8: 
addr = 4, data = 3 and color = RED

Number of indexes for data >= 3 and color == RED is 1
Element 1 for popped last index = 8: 
addr = 4, data = 3 and color = RED
unique_index method
function void unique_index_method();
  int idx_q[$], idx;
  int qsize;
   
  idx_q = arr.unique_index();
  $display("unique element in arr = %p", idx_q);
    
  // Find all idx having element as RED color
  idx_q = tr_assoc_arr.unique_index with (item.addr);
  qsize = idx_q.size;
  $display("Number of indexes having unique addr = %0d", qsize);
    
  for(int i = 0; i < qsize; i++) begin
    idx = idx_q.pop_front();
    $display("Element %0d for popped index = %0d: ",i+1, idx);
    tr_assoc_arr[idx].print();
  end
endfunction
Corresponding output:
-------------------------------------
-------- unique_index method --------
-------------------------------------
unique element in arr = '{0, 1, 2, 3, 4, 5, 7}
Number of indexes having unique addr = 4
Element 1 for popped index = 3: 
addr = 1, data = 7 and color = RED
Element 2 for popped index = 5: 
addr = 2, data = 7 and color = RED
Element 3 for popped index = 8: 
addr = 4, data = 3 and color = RED
Element 4 for popped index = 15: 
addr = 5, data = 2 and color = YELLOW
Execute complete code

Methods having mandatory and optional ‘with’ clause

The below table shows what all methods ‘with’ clause is mandatory or optional to use.

Type

Mandatory ‘with’ clause methods

Optional ‘with’ clause methods

Element Locator

find

unique

find_first

min

find_last

max

Index Locator

find_index

unique_index

find_first_index

find_last_index

System Verilog Tutorials