SFXList is data structure for operating a multiple of the elements as a two-way linked list. Memory allocation and release will be performed for each element.

SFXList and SFXArray

In the SFXList class, inserting or deleting an element is only to maintain the pointers of the element in question and the neighboring elements. On the other hand, in the SFXArray class, it is necessay to to move elements after the element in question in the internal buffer memory. Therefore, inserting or deleting an element is faster than in the SFXArray class. In the SFXList class, accessing an element needs to be traversed via a two-way linked list. On the other hand, in the SFXArray class, an element can be directly accessed using the index. Therefore, accessing an element is slower than in the SFXArray class.

In SFXList, memory allocation and release will be performed for each element. Since insertion and deletion of an element is only to maintain the pointers of the element in question and the neighboring elements, it is very fast.

The code below is to define the list with data of the SInt32 type as elements.

// define the list with data of the SInt32 type as elements
SFXList<SInt32> list;

// : list = ()

The code below is to append 4 elements into the stack with the SFXList::InsertLast function.

// current status: list = ()

list.InsertLast(3);    // in case of list, memory allocation will be performed for each element
// current status: list = (3)

list.InsertLast(-15);
// current status: list = (3, -15)

list.InsertLast(0);
// current status: list = (3, -15, 0)

list.InsertLast(1003);
// current status: list = (3, -15, 0, 1003)

	Note
	Every time the SFXList::InsertLast function is called, heap memory area for the element will be allocated. In an array, heap memory area will be allocated by the cluster size.

The code below is to insert elements into the list with the SFXList::Insert function. Since there is no need to move all elements after the element in question as the array, insertion of an element is faster.

// insert elements into list

// current status: list = (3, -15, 0, 1003)
// insert 99 after the 2nd element
list.Insert(2, 99);
// current status: list = (3, -15, 99, 0, 1003)

// insert -100 at the top
list.InsertFirst(-100);
// current status: list = (-100, 3, -15, 99, 0, 1003)

To get the size (number of the elements) of the list, call the SFXList::GetSize function.

// current status: list = (-100, 3, -15, 99, 0, 1003)

SInt32 n = list.GetSize();  // n = 6

Different from array, an element of the list cannot be accessed by specifying the index in the operand of the indexer operator such as the SFXArray::operator[] operator. But it can be accessed by specifying the index in the argument of the SFXList::Get / SFXList::Set function.

	Note
	Accessing of an element of the list using the SFXList::Get / SFXList::Set function is not direct accessing as array but traversing the link of the list elements. Therefore, it will take that much more time.

// access an element of list using not the [] operator but the Get/Set function

// current status: list = (-100, 3, -15, 99, 0, 1003)

// get the 2nd element of list
n = list.Get(1);  // n = 3
// "n = list[1];" is an invalid statement.

// get the 3rd element of list to 6
list.Set(2, 6);
// "list[2] = 6;" is an invalid statement.

// current status: list = (-100, 3, 6, 99, 0, 1003)

The top or last element can be obtained with the SFXList::GetFirst / SFXList::GetLast function.

// current status: list = (-100, 3, 6, 99, 0, 1003)

// get the first element
SInt32 first = list.GetFirst(); // first = -100

// get the last element
SInt32 last  = list.GetLast();  // last  = 1003

To remove the elements of the list, call the SFXList::Remove function.

// current status: list = (-100, 3, 6, 99, 0, 1003) 

// delete elements from the 4th element to the 5th element
list.Remove(3, 5); // list = (-100, 3, 6, 1003) 

// current status: list = (-100, 3, 6, 1003) 

	Note
	If the element is of the pointer type, the heap memory area which the pointer points to will not be released after the element is removed. Note that memory leakage may occur because of this.

To remove all elements of the list, call the SFXList::Clear function. This function releases the internal buffer.

// current status: list = (-100, 3, 6, 1003) 

// remove all elements of list
list.Clear(); 

// current status: list = ()
// internal buffer will be released

The code below is to search the element specified in the argument or check whether or not it exists. The SFXList::FirstIndexOf / SFXList::LastIndexOf function searches the element and gets the index. The SFXList::Contains function checks whether or not the list includes the element.

	Tip
	To update the element with the specified index, use the SFXList::Set function.

// current status: list = ()

// insert 5 elements into list
SInt32 i;
for (i = 0; i < 5 ; ++i) {

    list.InsertLast(10 * (i - 2) * (i - 2));
}

// current status: list = (40, 10, 0, 10, 40)

// set 3rd element to 100
list.Set(2, 100);

// current status: list = (40, 10, 100, 10, 40)

SInt32 x;
Bool   b;

// search the first element with the value of 10 and get its index
x = list.FirstIndexOf(10);     // x = 1

// search the first element with the value of 5 and get its index
x = list.FirstIndexOf(5);      // x = -1: since the element in question does not exist

// search the last element with the value of 10 and get its index
x = list.LastIndexOf(10);      // x = 3

// check whether or not the element with the value of 100 exists
b = list.Contains(100);        // b = true

// check whether or not the element with the value of 0 exists
b = list.Contains(0);          // b = false

To traverse the elements of the list, use the enumerator or the iterator. In case of the iterator, an element can be inserted or deleted.

SFXList<SInt32>::Enumerator etor = list.GetFirstEnumerator();
SInt32 i(0);

while(etor.HasNext()) {

    SInt32 n = etor.GetNext(); // get the element

    // display n in the BREW Output Window
    TRACE("#: %d, Value: %d", i++, n);
}

SFXList<SInt32>::Iterator itor = list.GetFirstIterator();
SInt32 i(0);

while(itor.HasNext()) {

    SInt32 n = itor.GetNext(); // get the element

    // display n in the BREW Output Window
    TRACE("#: %d, Value: %d", i++, n);
}