Nevertheless, it still pays to learn how to use Qt's own container classes. STL is not easy to learn, and when all you want to do is put some strings in a list and iterate over it, you can just as well use the Qt classes. Of course, these classes are not as sophisticated as the STL classes, and there aren't quite as many of them. However, if Qt contains what you need, I would suggest giving it a try. You could even save some memory in your application, since the container classes from Qt are linked to your program anyway, and it is reasonable to assume that compiler vendors will make linkage to the STL optional.

An important thing to distinguish about container classes is whether they are value based or reference based. Value based containers store a copy of whatever you put into them, and when you ask for the item back, you get another copy. This result can lead to a lot of copying, though, and is not always what you want. On the other hand, you never need to worry about ownership (i.e., who is allowed to do what with the item in the container) because all items are copies. Reference-based containers, on the other hand, only store a pointer to the item in question. This storage has the advantage that no copying needs to occur (and is the only option for classes for which copying is explicitly prohibited -- i.e., the copy constructor and the assignment operator are made private). The disadvantage is that you need to be careful about ownership: who has the right to delete a pointer in the container? The container itself or some owner outside? If it is not the container, you must remember that you need to take the pointer out of the container when you delete the corresponding object. Otherwise, you have so-called dangling pointers in your container, indicating that a disaster is bound to happen.

Whether you should choose a reference-based or a value-based container class depends completely on the task at hand, but it is good to know that both exist in Qt (unlike in STL, for example).

If you will mainly add new members at the end and plan to retrieve the members one after the other (and probably in the same order in which you put them), use the reference-based QPtrList or its value-based counterpart QValueList. On the other hand, if you need maximum flexibility for storage and retrieval of the elements, use the reference-based QPtrDict, QIntDict, or QPtrDict, or their value-based counterpart QMap. Which one you choose should depend on how you want to access the elements. If you access them by an integer number, use QIntDict; if you access them by a string, use QPtrDict; if you access them by another object, use QPtrDict. QMap lets you use any type of key, since you can specify that yourself.

Basic Usage

After you have chosen a container class to use, you have to know how to create objects of this class and how to insert and retrieve members.

In this section, we describe only the reference-based classes. The techniques for working with the value-based classes are completely different. There is no technical reason why this is so; the explanation given by the authors of Qt is that since these two types of containers are so different, their interface should be different as well. We are not so convinced by this explanation, but we have to live with it anyway. The next section covers how to use value-based container classes.

Since the reference-based container classes simply store a pointer to the contained object, it would suffice if all classes accepted void*. This would keep type safety to a minimum when using container classes, though, so you have to define a type that accepts pointers to one kind of object. If you know about templates in C++, you probably suspect that Qt uses them as well, which is exactly the case.[1]

We will explain the use of container classes with the class QPtrList. Use of the other classes is basically the same; other classes have slightly different methods for insertion, retrieval, and removal.

Let's assume that you are writing a program for managing your stamp collection. You might have already created a class Stamp, and now need a container in which to store objects of this type. Here's how you declare a type StampList with templates:

typedef QPtrList<Stamp> StampList;

This example says that StampList is a special kind of QPtrList that accepts pointers to Stamp objects as its members. It works only if Stamp has already been defined; a forward reference is not enough. Note that you do not have to provide the asterisk to indicate that pointers are to be stored. The reference-based container classes already assume that you want to store a pointer because that is the only thing they can store. Using the asterisk would still be legal C++ code:

typedef QPtrList<Stamp*> StampList;

This line of code means that StampList stores pointers to Stamp objects.

After you create the appropriate type, you can create an object of the container class and insert items in it:

StampList stamplist; 
... 
Stamp stamp1; 
Stamp stamp2; 
Stamp stamp3; 
... 
stamplist.append( &stamp1 ); 
stamplist.insert( 0, &stamp2 ); 
stamplist.insert( 1, &stamp3 );

The append() method inserts items at the end. When using insert(), you have to pass the position at which the item should be inserted.

When you use one of the index containers QPtrDict, QIntDict, and QPtrDict, pass the key as the first parameter and the value as the second parameter to insert().

Members are taken out of a collection with remove() (see the Qt reference documentation for the correct parameters).

For retrieval in dictionary classes, use find() or the synonymous operator[]:

QPtrDict<Stamp> stampdict; 
... 
Stamp stamp1; 
... 
stampdict.insert( "somekey", &stamp1 ); 
Stamp* result = stampdict["somekey"]; 
...

For QPtrList, your best bet is to start at the beginning with first(), or at the end with last(), and then retrieve the elements one by one with next() or prev(). You know you are at the end of the list when one of these methods returns a 0 pointer.

All container classes support the methods clear(), which removes all elements from the container, and count(), which returns the number of stored elements.

typedef QPtrList<Stamp> StampList; 
... 
StampList* stamplist = new StampList(); 
stamplist->setAutoDelete( true ); 
... 
list->append( new Stamp( "Blue Mauritius", 3000000 ) ); 
list->append( new Stamp( "Tre Skilling Banco", 1800000 ) ); 
... 
delete stamplist; // the two Stamp objects are deleted automatically

By default, retrieving a cached object with either find() or operator[] makes it the least recently used entry. This assumes a cache-access pattern in which all cached objects are likely to be retrieved in turn, or in which all cached objects have the same probability of being retrieved. If this pattern does not fit your application because retrieving an object from the cache increases the probability that it will be retrieved again in the near future (or at least does not reduce the probability), you can pass false as the second parameter to find(). This pass prevents the cached object from being marked as the least recently used. In this case, operator[] cannot be used.

Iterators

typedef QPtrList<Stamp> StampList; 
StampList stamplist; 
stamplist.setAutoDelete( true ); 
stamplist.append( new Stamp( "Blue Mauritius", 3000000 ) ); 
stamplist.append( new Stamp( "Tre Skilling Banco", 1800000 ) ); 
... 
typedef QPtrListIterator<Stamp> StampListIterator; 
StampListIterator myiterator( stamplist ); 
for( myiterator.toFirst(); myiterator.current(); ++myiterator ) 
{ 
  qDebug( "%s is worth %d\n", myiterator.current()->name(), 
      myiterator.current()->value() ); 
}

Note that the type of the iterator fits the type of the container iterated on exactly, and that the container is passed as an argument in the iterator's constructor.

The dictionary containers do not have an intrinsic order, so you will never know which order the members will come back in when iterating over the container. If you need to maintain the order, use QPtrList.

There is a danger associated with the incorrect use of iterators. If you retrieve the current object and do a "dangerous operation," such as removing this object from the container, incrementing the iterator will skip over the next object in question, thus leaving it out. Therefore, you should always increment the iterator right after taking the current element. Here is some boilerplate code that you can use:

QPtrList<X>* mylist; 
QPtrListIterator<X> iterator( *mylist ); 
X *obj; 
 
while( ( obj = iterator.current() ) ) { 
    ++iterator; // iterator now points to the next object to iterate on 
    obj->doAnyOperation(); // even "dangerous" ones 
}

Stacks and Queues

The simplest case, inserting items one after the other, can still be done without iterators. It looks very similar to the reference-based version:

typedef QValueList<Stamp> ValueStampList;
ValueStampList stamplist; 
... 
Stamp stamp1; 
Stamp stamp2; 
Stamp stamp3; 
... 
stamplist.append( stamp1 ); 
stamplist.append( stamp2 ); 
stamplist.append( stamp3 );

Note how we use append here -- i.e., we append the stamps to the end of the list.

For removing an item, you already need an iterator. Let's take an easy case first and say that we want to remove the first item in the list. We get an iterator pointing to the first item by calling begin() on the list:

stamplist.remove( stamplist.begin() );

You might suspect now that to remove the last item from the list, you need to use end() instead of begin():

// WRONG!
stamplist.remove( stamplist.end() );

since the iterator returned by end() does not point to the last element of the list, but rather behind the last element where no more elements are found. The correct function in this case would be fromLast(), which returns an iterator pointing to the last element.

To insert an element before another one, use insert() and pass it both an iterator pointing to the element before which the new one should be inserted and the new one. To insert a new element at the beginning of the list, you would do as follows:

...
Stamp stamp4;
stamplist.insert( stamplist.begin(), stamp4 );

Remember that we said that the iterator returned by end() points behind the last element in the list? Thus, the following two operations are equivalent:

// Appends to the list
stamplist.append( somestamp );

and:

// Appends to the list as well
stamplist.insert( stamplist.end(), somestamp );

Many methods, such as find(), return an iterator. To get at the object that actually hides behind this iterator, just use the ordinary dereferencing operator *:

Stamp somestamp = *( stamplist.find( someotherstamp ) );

It is probably no surprise that iterating over a value-based container involves iterators as well. The pattern is exemplified here with stamp again:

...
typedef QValueListIterator<Stamp> StampListIterator;
...
for( StampListIterator it = stamplist.begin(); it != stamplist.end(); ++it ) 
  // do something with *it

This example basically says to loop over all iterator values starting with the one pointing to the first element in the container and continue to do so until the last element has been seen (i.e., until the iterator points behind it).