Q3PtrList Class Reference
[Qt3Support module]

Example:

 class Employee
 {
 public:
     Employee() : sn( 0 ) { }
     Employee( const QString& forename, const QString& surname, int salary )
         : fn( forename ), sn( surname ), sal( salary )
     { }

     void setSalary( int salary ) { sal = salary; }

     QString forename() const { return fn; }
     QString surname() const { return sn; }
     int salary() const { return sal; }

 private:
     QString fn;
     QString sn;
     int sal;
 };

 Q3PtrList<Employee> list;
 list.setAutoDelete( TRUE ); // the list owns the objects

 list.append( new Employee("John", "Doe", 50000) );
 list.append( new Employee("Jane", "Williams", 80000) );
 list.append( new Employee("Tom", "Jones", 60000) );

 Employee *employee;
 for ( employee = list.first(); employee; employee = list.next() )
     cout << employee->surname().latin1() << ", " <<
             employee->forename().latin1() << " earns " <<
             employee->salary() << endl;
 cout << endl;

 // very inefficient for big lists
 for ( uint i = 0; i < list.count(); ++i )
     if ( list.at(i) )
         cout << list.at( i )->surname().latin1() << endl;

The output is

 Doe, John earns 50000
 Williams, Jane earns 80000
 Jones, Tom earns 60000

 Doe
 Williams
 Jones

Q3PtrList has several member functions for traversing the list, but using a Q3PtrListIterator can be more practical. Multiple list iterators may traverse the same list, independently of each other and of the current list item.

In the example above we make the call setAutoDelete(true). Enabling auto-deletion tells the list to delete items that are removed. The default is to not delete items when they are removed but this would cause a memory leak in the example because there are no other references to the list items.

When inserting an item into a list only the pointer is copied, not the item itself, i.e. a shallow copy. It is possible to make the list copy all of the item's data (deep copy) when an item is inserted. insert(), inSort() and append() call the virtual function Q3PtrCollection::newItem() for the item to be inserted. Inherit a list and reimplement newItem() to have deep copies.

When removing an item from a list, the virtual function Q3PtrCollection::deleteItem() is called. Q3PtrList's default implementation is to delete the item if auto-deletion is enabled.

The virtual function compareItems() can be reimplemented to compare two list items. This function is called from all list functions that need to compare list items, for instance remove(const type*). If you only want to deal with pointers, there are functions that compare pointers instead, for instance removeRef(const type*). These functions are somewhat faster than those that call compareItems().

List items are stored as void* in an internal Q3LNode, which also holds pointers to the next and previous list items. The functions currentNode(), removeNode(), and takeNode() operate directly on the Q3LNode, but they should be used with care. The data component of the node is available through Q3LNode::getData().

The Q3StrList class is a list of char*. It reimplements newItem(), deleteItem() and compareItems(). (But see QStringList for a list of Unicode QStrings.)

See also Q3PtrListIterator.

Member Function Documentation

 if ( list.findRef( item ) != -1 )
     list.remove();