13.4 - Creating Linked Lists with DtList

Note

Use of DtList has been superceded by use of std:list<>. MAK strongly recommends that you use std::list<> in all new code. DtList will continue to be supported for backwards compatibility.

DtList (defined in vlList.h) provides a general linked-list capability in VR-Link. To enable DtList to be used to represent a list of any type of object, pointers to the objects being listed are represented by void*, and must be explicitly cast back to the data type you are listing when you want to inspect data in the list.

Within VR-Link, a DtList is used to represent the list of articulated parts that an entity possesses, the list of HLA objects in the exercise, and other such lists. For these reasons, you may need to work with DtLists even if you do not choose to use them to represent your own lists.

A DtList is constructed as follows:

DtList list;

Elements can be added to a DtList using:

• addToStart()
• addToEnd()
• addBefore()
• addAfter()
• add() – which is equivalent to addToEnd().

These functions return a pointer to a DtListItem – an envelope in which your data gets wrapped before insertion into the list.

These functions also take a pointer to the element to be added. (As an exception, we sometimes store simple data types that are <=32 bits directly in the list rather than by using pointers.) These pointers must remain valid for the duration of the time they are in the list. For example, the address of automatic variables should not be put in a list if the list remains beyond the scope of the automatic variables. As a result, in general, the pointers in a list should typically be from new'ed data.

DtList's first() and last() functions return pointers to DtListItems that hold the first and last elements of the list.

You can use DtListItem::data() to get back the pointer you added to the list.

The functions first() and last() return NULL when the list is empty.

The DtListItem prev() and next() member functions facilitate iterating through a list. These functions return NULL when the beginning and end of the list have been reached, respectively. Thus, you can iterate through the elements in a list as follows:

DtList list;
   ...
for (DtListItem* item = list.first(); item; item = item->next());

The following example adds several items to a list (in this case instances of class A), and pulls them out of the list later:

// Definition of class A
class A
{
public:
   A(int num) { a = num; }
   int a;
};
// Create the list
DtList list;
// Create three instances of class A
A* a1 = new A(1);
A* a2 = new A(2);
A* a3 = new A(3);
// Add the instances to the list
list.add(a1);
list.add(a2);
list.add(a3);
// Iterate through the list, inspect the data
for (DtListItem* item = list.first(); item; item = item->next())
{
   // Use DtListItem::data to get back the pointer you added.
   // You must cast the pointer back to an A* from a void*
   A* current = (A*) item->data();   
   printf("%d\n", current->a);
}

[<< Coordinate Conversions] [Home] [Top of Page] [Diagnostic Utilities >>]