A list is an ordered collection of elements of the same type. A list is always indexed contiguously either in ascending order or in descending order. A list type is declared using the following declaration:

type list_type is list(<> or range) of another_type;

Example:

Type list_a_type is list (<>) of INTEGER;
Type list_b_type is list (0 to 5) of BIT_VECTOR(0 to 3);
Type list_c_type is list (3 downto 0) of STRING(0 to 5);

When a range of <> is specified, the list is of an unspecified maximum length (0 to INTEGER’HIGH-1 is default). When a range is specified, the range specifies the MAX number of elements that can be contained in the list. The range is only a constraint. The head of the list is always the leftmost index.

'LEFT and 'RIGHT attributes can be used on a list type to access its bounds – these attributes when used with a type that has range of <> yield 0 and INTEGER’HIGH-1 respectively.

During list operations, the list is always anchored at the leftmost index and grows towards the right. Indices are adjusted to be always consecutive.

Examples of object decls:

Variable usb_fan: list_I_type; // empty by default.
Signal usb_data: list_b_type := (“001”, “000”, “000”); // list
 // has three elements indexed from 0 to 2.
Signal phy_recd: list_b_type := (”001”, ”000”); // will
 // create a 2 element list, indexed from 0 to 1.

The following attributes can be applied to objects of a list type to perform list operations.

• List_object'DELETE [(index)] – deletes the element at specified index (and all indices adjusted appropriately). If index is not in within list length, returns false, else returns true. If no index specified, all elements in the list are deleted and a true is returned. Deleting an empty list still returns a true.
• List_object'INSERT (value [, index]) – inserts a value at the specified index. All other indices/values to the right are adjusted appropriately. If list size becomes greater than specified size, a value of false is returned and the insert does not take place. A true is returned if the insert is successful. If no index specified, insert occurs at end of list (tail). To add to head of list, use list_type’LEFT as index. The value could be a value of the list type or another list type. If value is another list, the new list is inserted at the specified position (always growing to the right). ).
  What will happen when b_list of size say 3 is added to a_list whose MAX size is set to 10, and a_list already has 8 elements? Should 2 elements of b_list be added or none will be added to a_list? The answer is that none of the elements will be added and a value of false is returned.
• List_object'LENGTH – returns the number of elements in the list. 0 if list is empty.
• List_object'SORT – sorts the list based on the values in the list in non-decreasing order based on the relational operator defined for the value type. Returns true if successful (if list changed).
• List_object'UNIQUE – deletes any duplicate values of the type in the list. (not necessarily numerical values – so bit_vector “000” is different from bit_vector “0000”). Returns true if successful (if list changed).
• List_object'REVERSE – reverses the order of elements in the list. Returns true if successful (if list changed).
• List_object'EXISTS(value) – Returns TRUE if the value being passed as argument exists within the list, else FALSE.
• List_object'INDEX(value) Returns an INTEGER denoting the index of the element which matches with the value argument. Returns –1 if the value doesn’t exist. The search happens from LEFT to RIGHT, search stops at the first match, so if there are multiple elements matching the value being searched, first index will be returned. To search from RIGHT side, do a REVERSE first and then perform a search.

You can assign a list to another list with an assignment statement. This creates a completely new copy of the list.

Usb_data ⇐ phy_recd;

You can initialize a list using an aggregate constant as shown in the example earlier.

Usb_data ⇐ (“100”, “111”);

You can also pass lists as arguments to subprograms (similar to arrays).

To write out values in a list, iterate on the list and write out each value.

Note: You can always build your own lists by using the new operator and access pointers.

1. How can we perform extraction?
   List_object’EXTRACT(<expr>) – returns a new list which is a sub list of List_object with its elements matching the <expr>. E.g. Type usb_pkts is list (<>) of usb_packet; Old_pkts = usb_pkts’EXTRACT(it.log_time > now);

   • *But how do we specify sub-field of the elements of any list? An existing HVL supports a key-word as “it” which refers to each element in a list.**
2. How do we support KEYed lists? I.e. say a list is created as USB packet.
   Type list_usb_pkts is list (<>) of usb_packet; usb_packet is a record data type with elements such as header, payload, uid etc. Now when a packet is received from DUT, user wants to search for the pkt with uid as KEY. One possible way is to declare the list as KEYed list and allow key based searching. Type list_usb_pkts is list (<>) of usb_packet (key : uid : bit_vector (31 downto 0) ); Rx_pkt_index = usb_pkts’KEY_INDEX (rx_pkt)
3. How can we do MIN and MAX?