In addition to the indexing operators, several built-in methods are provided that allow users to analyze and manipulate associative arrays, as well as iterate over its indices or keys.
The syntax for the num() method is:
function int num();
The num() method returns the number of entries in the associative array. If the array is empty, it returns 0.
int imem[*];
imem[ 2’b3 ] = 1;
imem[ 16’hffff ] = 2;
imem[ 4b’1000 ] = 3;
$display( "%0d entries\n", imem.num ); // prints "3 entries"
The syntax for the delete() method is:
function void delete( [input index] );
Where index is an optional index of the appropriate type for the array in question.
If the index is specified, then the delete() method removes the entry at the specified index. If the entry to be deleted does not exist, the method issues no warning.
If the index is not specified, then the delete() method removes all the elements in the array.
int map[ string ];
map[ "hello" ] = 1;
map[ "sad" ] = 2;
map[ "world" ] = 3;
map.delete( "sad" ); // remove entry whose index is "sad" from "map"
map.delete; // remove all entries from the associative array "map"
The syntax for the exists() method is:
function int exists( input index );
Where index is an index of the appropriate type for the array in question.
The exists() function checks if an element exists at the specified index within the given array. It returns 1 if the element exists, otherwise it returns 0.
if ( map.exists( "hello" ))
map[ "hello" ] += 1;
else
map[ "hello" ] = 0;
The syntax for the first() method is:
function int first( ref index );
Where index is an index of the appropriate type for the array in question.
The first() method assigns to the given index variable the value of the first (smallest) index in the associa-tive array. It returns 0 if the array is empty, and 1 otherwise.
string s;
if ( map.first( s ) )
$display( "First entry is : map[ %s ] = %0d\n", s, map[s] );
The syntax for the last() method is:
function int last( ref index );
Where index is an index of the appropriate type for the array in question.
The last() method assigns to the given index variable the value of the last (largest) index in the associative array. It returns 0 if the array is empty, and 1 otherwise.
string s;
if ( map.last( s ) )
$display( "Last entry is : map[ %s ] = %0d\n", s, map[s] );
The syntax for the next() method is:
function int next( ref index );
Where index is an index of the appropriate type for the array in question.
The next() method finds the entry whose index is greater than the given index. If there is a next entry, the index variable is assigned the index of the next entry, and the function returns 1. Otherwise, index is unchanged, and the function returns 0.
string s;
if ( map.first( s ) )
do
$display( "%s : %d\n", s, map[ s ] );
while ( map.next( s ) );
The syntax for the prev() method is:
function int prev( ref index );
Where index is an index of the appropriate type for the array in question.
The prev() function finds the entry whose index is smaller than the given index. If there is a previous entry, the index variable is assigned the index of the previous entry, and the function returns 1. Otherwise, the index is unchanged, and the function returns 0.
string s;
if ( map.last( s ) )
do
$display( "%s : %d\n", s, map[ s ] );
while ( map.prev( s ) );
If the argument passed to any of the four associative array traversal methods first, last, next, and prev is smaller than the size of the corresponding index, then the function returns –1 and shall copy only as much data as can fit into the argument.
For example:
string aa[*];
byte ix;
int status;
aa[ 1000 ] = "a";
status = aa.first( ix );
// status is –1
// ix is 232 (least significant 8 bits of 1000)
Associative arrays can be assigned only to another associative array of a compatible type and with the same index type. Other types of arrays cannot be assigned to an associative array, nor can associative arrays be assigned to other types of arrays, whether fixed-size or dynamic.
Assigning an associative array to another associative array causes the target array to be cleared of any existing entries, and then each entry in the source array is copied into the target array.
Associative arrays can be passed as arguments only to associative arrays of a compatible type and with the same index type. Other types of arrays, whether fixed-size or dynamic, cannot be passed to subroutines that accept an associative array as an argument. Likewise, associative arrays cannot be passed to subroutines that accept other types of arrays.
Passing an associative array by value causes a local copy of the associative array to be created.
Associative array literals use the {index:value} syntax with an optional default index. Like all other arrays, an associative array can be written one entry at a time, or the whole array contents can be replaced using an array literal.
For example:
// an associative array of strings indexed by 2-state integers,
// default is "foo".
string words [int] = {default: "foo"};
// an associative array of 4-state integers indexed by strings, default is –1.
integer table [string] = {"Peter":20, "Paul":22, "Mary":23, default:-1 };
If a default value is specified, then reading a non-existent element shall yield the specified default value. Otherwise, the default initial value is as described in Table 2-7 shall be returned.