Skip to content

List

v2.2.0

Properties

  • Ordered by index.
  • Randomizable when its data_type is randomizable (e.g., randomizable scalar or aggregate of randomizable scalar).
  • Element and data_type can be any scalar or aggregate of scalar.
  • Index must be non-negative integer.
  • Can be nested by any collection types (e.g., array, list, map or set).

Declarations

v2.2.0

Not support yet

PSSGen: Not support chandle as data_type.

List can be declared by following syntax:

list<data_type> identifier

1
2
3
4
5
6
list<int     > intList   ;  //  intList   : {}
list<bit [8] > byteList  ;  //  byteList  : {}
list<bool    > boolList  ;  //  boolList  : {}
list<string  > stringList;  //  stringList: {}
list<eSTR2NUM> enumList  ;  //  enumList  : {} (1)
list<sSTR2NUM> structList;  //  structList: {} (2)

  1. Assume defined enum type before 

    1
2
3
    enum eSTR2NUM {
    ZERO, ONE, TWO
};

  2. Assume defined struct type before 

    1
2
3
4
    struct sSTR2NUM {
    string stringVal;
    int intVal;
};

Declare list by rand keyword

Not support yet v2.1

1
2
3
rand list<int    > intList   ;
rand list<bit [8]> byteList  ;
rand list<string > stringList;

Initialization Assignment

v2.2.0

PSSGen: Support bit, int, and string as element in initialization assignment.

Not support yet

PSSGen: Not support bool, enum, float32, float64, chandle, and struct as element in initialization assignment.

List can be assigned at declaration; otherwise, it will be initialized to empty aggregate literal ({}). 

1
2
3
4
list<int    > intList    = {1    , 2    };  //  intList   : {1    , 2    }
list<bit [8]> byteList   = {8'b01, 8'b10};  //  byteList  : {8'b01, 8'b10}
list<bool   > boolList   = {false, true };  //  boolList  : {false, true }
list<string > stringList = {"1"  , "2"  };  //  stringList: {"1"  , "2"  }

List Operators

Operator Description
[] Used to access a specific element of a list by given index, which must be a non-negative integer.
= Create a copy of the list-type expression on the RHS and assigns it to the list on the LHS.
== Evaluates to true if both sizes are equal and all elements with corresponding indexes are equal.
!= Evaluates to true whether both sizes are not equal or if any element with corresponding index is not equal.
in Evaluates to true if element on the LHS of in is exists in the list.
foreach Iterates over the list's elements.

List Methods

Method Description
int size() Returns the number of elements in the list.
clear() Removes all elements from the list.
<data_type> delete(int index) Moves out the element at the specified index, which must be a non-negative integer.
insert(int index, data_type element) Adds the element to the specified index, and all elements at and beyond the index are moved by one.
<data_type> pop_front() Moves out the first element from the list. Same as delete(0).
push_front(data_type element) Adds the element to the beginning of the list. Same as insert(0, element).
<data_type> pop_back() Moves out the last element from the list. Same as delete(size()-1).
push_back(data_type element) Adds the element to the end of the list. Same as insert(size()-1, element).
set<data_type> to_set() Returns all elements to a set-type.
shuffle()
v2.3.0 v2.1		 Randomizes orders of elements.

Index operator []

v2.2.0

PSSGen: Support bit, int, and string as element for index operator [].

Not support yet

PSSGen: Not support bool, enum, float32, float64, chandle, and struct as element for index operator [].

Used to access a specific element of a list by given index, which must be a non-negative integer. 

1
2
3
4
list<int> intList = {1, 2, 3};

int intVal = intList[1];    //  intVal: 0 -> 2
int intVal = intList[9];    //  ILLEGAL (1)

  1. The index is out of bounds.

Warning

Index should smaller than size() of the list.

Assignment operator =

v2.2.0

PSSGen: Support bit, int, and string as element for assignment operator =.

Not support yet

PSSGen: Not support bool, enum, float32, float64, chandle, and struct as element for assignment operator =.

Create a copy of the list-type expression on the RHS and assigns it to the list on the LHS. 

1
2
3
list<int> intList = {1, 2, 3};

intList = {2, 3, 4};        //  intList: {1, 2, 3} -> {2, 3, 4}

Note

Operator that modify contents can only be used within exec block or native function.

Equality operator ==

v2.2.0

Evaluates to true if both sizes are equal and all elements with corresponding indexes are equal. 

1
2
3
4
5
6
7
8
list<int   > intList_0  = { 1 ,  2 ,  3      };
list<int   > intList_1  = { 1 ,  2 ,  3 ,  4 };
list<string> stringList = {"1", "2", "3"};

bit bitVal_0, bitVal_1, bitVal_2;
if (intList_0 == intList_0 ) bitVal_0 = 1;  //  bitVal_0: 0 -> 1; (1)
if (intList_0 == intList_1 ) bitVal_1 = 1;  //  bitVal_1: 0 -> 0; (2)
if (intList_0 == stringList) bitVal_2 = 1;  //  ILLEGAL (3)

  1. Equalize size and all elements with corresponding indexes.
  2. Inequalize size.
  3. Different data_type are incomparable.

Warning

Different data_type of two lists should NOT be compared.

Inequality operator !=

v2.2.0

Evaluates to true whether both sizes are not equal or if any element with corresponding index is not equal. 

1
2
3
4
5
6
7
8
list<int   > intList_0  = { 1 ,  2 ,  3      };
list<int   > intList_1  = { 1 ,  2 ,  3 ,  4 };
list<string> stringList = {"1", "2", "3"};

bit bitVal_0, bitVal_1, bitVal_2;
if (intList_0 != intList_0 ) bitVal_0 = 1;  //  bitVal_0: 0 -> 0 (1)
if (intList_0 != intList_1 ) bitVal_1 = 1;  //  bitVal_1: 0 -> 1 (2)
if (intList_0 != stringList) bitVal_2 = 1;  //  ILLEGAL (3)

  1. Equalize size and all elements with corresponding indexes.
  2. Inequalize size.
  3. Different data_type are incomparable.

Warning

Different data_type of two lists should NOT be compared.

Set membership operator in

v2.2.0

Evaluates to true if element on the LHS of in is exists in the list. 

1
2
3
4
5
6
list<int> intList = {1, 2, 3};

bit bitVal_0, bitVal_1, bitVal_2;
if ( 1  in intList) bitVal_0 = 1;           //  bitVal_0: 0 -> 1
if ( 0  in intList) bitVal_1 = 1;           //  bitVal_1: 0 -> 0
if ("1" in intList) bitVal_2 = 1;           //  ILLEGAL (1)

  1. Different data_type between LHS of in and the list's element on RHS of in.

Warning

Data_type of element on LHS of in should be SAME as the list's element on RHS of in.

foreach statement

v2.2.0

Iterates over the list's elements.

Look at Procedural/foreach for more information. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
list<int> intList = {4, 5, 6};
int intVal_0 = 0;
int intVal_1 = 0;
int intVal_2 = 0;

foreach (i : intList[j]) {
    intVal_0 = i;           //  intVal_0: 0 -> 4 -> 5 -> 6
    intVal_1 = j;           //  intVal_1: 0 -> 0 -> 1 -> 2
    intVal_2 = intList[j];  //  intVal_2: 0 -> 4 -> 5 -> 6
}

function int size()

v2.2.0

Returns the number of elements in the list. 

1
2
3
list<int> intList = {1, 2, 3};

int intVal = intList.size();        //  intVal: 0 -> 3

function void clear()

v2.2.0

Removes all elements from the list. 

1
2
3
list<int> intList = {1, 2, 3};

intList.clear();                    //  intList: {1, 2, 3} -> {}

Note

Method that modify contents can only be used within exec block or native function.

function <data_type> delete(index)

v2.2.0

Moves out the element at the specified index, which must be a non-negative integer. 

1
2
3
4
list<int> intList = {1, 2, 3};

int intVal = intList.delete(1);     //  intVal: 0 -> 2; intList: {1, 2, 3} -> {1, 3}
int intVal = intList.delete(5);     //  ILLEGAL (1)

  1. The index is out of bounds.

Warning

The index must be smaller than size() of the list.

Note

Method that modify contents can only be used within exec block or native function.

function void insert(index, element)

v2.2.0

PSSGen: Support bit, int, and string as element of insert().

Not support yet

PSSGen: Not support bool, enum, float32, float64, chandle, and struct as element of insert().

Adds the element to the specified index, and all elements at and beyond the index are moved by one. 

1
2
3
4
5
6
list<int> intList = {1, 2, 3};

intList.insert(1, 6);               //  intList: {1, 2, 3} -> {1, 6, 2, 3}
intList.insert(4, 7);               //  intList: {1, 6, 2, 3} -> {1, 6, 2, 3, 7}
intList.insert(9, 8);               //  ILLEGAL (1)
intList.insert(0, "1");             //  ILLEGAL (2)

  1. The index is larger than size() of the list.
  2. The data_type of elements are not the same.

Warning

The index should NOT larger than size() of the list.

Note

Method that modify contents can only be used within exec block or native function.

function <data_type> pop_front()

v2.2.0

Moves out the first element from the list. Same as delete(0). 

1
2
3
list<int> intList = {1, 2, 3};

int intVal = intList.pop_front();   //  intVal: 0 -> 1; intList: {1, 2, 3} -> {2, 3}

Note

Method that modify contents can only be used within exec block or native function.

function void push_front(element)

v2.2.0

PSSGen: Support bit, int, and string as element of push_front().

Not support yet

PSSGen: Not support bool, enum, float32, float64, chandle, and struct as element of push_front().

Adds the element to the beginning of the list. Same as insert(0, element). 

1
2
3
list<int> intList = {1, 2, 3};

intList.push_front(4);              //  intList: {1, 2, 3} -> {4, 1, 2, 3}

Note

Method that modify contents can only be used within exec block or native function.

function <data_type> pop_back()

v2.2.0

Moves out the last element from the list. Same as delete(size()-1). 

1
2
3
list<int> intList = {1, 2, 3};

int intVal = intList.pop_back();    //  intVal: 0 -> 3; intList: {1, 2, 3} -> {1, 2}

Note

Method that modify contents can be used within exec block or native function.

function void push_back(element)

v2.2.0

PSSGen: Support bit, int, and string as element of push_back().

Not support yet

PSSGen: Not support bool, enum, float32, float64, chandle, and struct as element of push_back().

Adds the element to the end of the list. Same as insert(size()-1, element). 

1
2
3
list<int> intList = {1, 2, 3};

intList.push_back(4);               //  intList: {1, 2, 3} -> {1, 2, 3, 4}

Note

Method that modify contents can only be used within exec block or native function.

function set<data_type> to_set()

v2.2.0

Returns all elements to a set-type. 

1
2
3
list<int> intList = {1, 2, 1};

set<int> intSet = intList.to_set(); //  intSet: {} -> {1, 2}

function void shuffle()

v2.3.0 v2.1

Randomizes orders of elements. 

1
2
3
list<int> intList = {1, 2};

intList.shuffle();                  //  intList: {1, 2} -> {1, 2} or {2, 1}

Note

Method that modify contents can only be used within exec block or native function.

Usage: use shuffle() to generate a unique random array

While unique become larger, the random solver can't solved within a limit iteration. Using shuffle() and repeat() can generate unique element for each variable.

1
2
3
4
5
6
array<bit [4], 4> nibbleArray;
constraint {
    unique {nibbleArray[0], nibbleArray[1], nibbleArray[2], nibbleArray[3]};
}
...
//  do something with solved nibbleArray

1
2
3
4
5
6
7
8
9
array<bit [4], 4> nibbleArray;
list <bit [4]   > element_pool;
exec pre_solve {
    repeat (i : 16) element_pool.push_back(i);  //  element_pool: {} -> {0..15}
    element_pool.shuffle();
    foreach(nibbleArray[i]) nibbleArray[i] = element_pool.pop_front();
}
...
//  do something with solved nibbleArray
Last update: 2023-10-26
Created: 2023-10-13