Qt Template Library

The Qt Template Library (QTL) is a set of templates that provide object containers. If a suitable STL implementation is not available on all your target platforms, the QTL can be used instead. It provides a list of objects, a vector (dynamic array) of objects, a map relating one type to another (also called a dictionary or associative array), and associated iterators and algorithms. A container is an object which contains and manages other objects and provides iterators that allow the contained objects to be accessed.

The QTL classes' naming conventions are consistent with the other Qt classes (e.g., count(), isEmpty()). They also provide extra functions for compatibility with STL algorithms, such as size() and empty(). Programmers already familiar with the STL map can use the STL-compatible functions if preferred.

Compared to the STL, the QTL only contains the most important features of the STL container API. Compared with the STL, QTL has no platform differences, but is often a little slower and often expands to less object code.

If you cannot make copies of the objects you want to store you should use QPtrCollection and friends, all of which operate on pointers rather than values. This applies, for example, to all classes derived from QObject. A QObject does not have a copy constructor, so using it as value is impossible. You may choose to store pointers to QObjects in a QValueList, but using QPtrList directly seems to be the better choice for this kind of application domain. QPtrList, like all other QPtrCollection based containers, provides far more sanity checking than a speed-optimized value based container.

If you have objects that implement value semantics, and the STL is not available on your target platform, the Qt Template Library can be used instead. Value semantics require at least:

• a copy constructor;
• an assignment operator;
• a defaultconstructor, i.e. a constructor that does not take any arguments.

Note that a fast copy constructor is absolutely crucial to achieve good overall performance of the container, since many copy operations will occur.

If you intend sorting your data you must implement operator<() for your data's class.

Good candidates for value based classes are QRect, QPoint, QSize, QString and all simple C++ types, such as int, bool or double.

The Qt Template Library is designed for speed. Iterators are extremely fast. To achieve this performance, less error checking is done than in the QPtrCollection based containers. A QTL container, for example, does not track any associated iterators. This makes certain validity checks, for example when removing items, impossible to perform automatically, but does lead to extremely good performance.

Iterators

    typedef QValueList<int> List;
    List list;
    for( List::Iterator it = list.begin(); it != list.end(); ++it )
        printf( "Number is %i\n", *it );

    typedef QMap<QString,QString> Map;
    Map map;
    for( Map::iterator it = map.begin(); it != map.end(); ++it )
        printf( "Key=%s Data=%s\n", it.key().ascii(), it.data().ascii() );

    typedef QValueVector<int> Vector;
    Vector vec;
    for( Vector::iterator it = vec.begin(); it != vec.end(); ++it )
        printf( "Data=%d\n", *it );

    typedef QValueList<int> List;
    List list;
    list << 42 << 100 << 1234 << 12 << 8;
    qHeapSort( list );

    List list2;
    list2 << 42 << 100 << 1234 << 12 << 8;
    List::Iterator b = list2.find( 100 );
    List::Iterator e = list2.find( 8 );
    qHeapSort( b, e );

    double arr[] = { 3.2, 5.6, 8.9 };
    qHeapSort( arr, arr + 3 );

    QString second( "Einstein" );
    QString name( "Albert" );
    qSwap( second, name );

    QValueList<int> list;
    list.push_back( 1 );               
    list.push_back( 1 );               
    list.push_back( 1 );               
    list.push_back( 2 );               
    int c = 0;
    qCount( list.begin(), list.end(), 1, c ); // c == 3

    QValueList<int> list;
    list.push_back( 1 );               
    list.push_back( 1 );               
    list.push_back( 1 );               
    list.push_back( 2 );               
    QValueListIterator<int> it = qFind( list.begin(), list.end(), 2 );

    QValueVector<int> vec(3);
    qFill( vec.begin(), vec.end(), 99 ); // vec contains 99, 99, 99

    QValueVector<int> v1(3);
    v1[0] = 1;
    v1[2] = 2;
    v1[3] = 3;

    QValueVector<int> v2(5);
    v2[0] = 1;
    v2[2] = 2;
    v2[3] = 3;
    v2[4] = 4;
    v2[5] = 5;

    bool b = qEqual( v1.begin(), v2.end(), v2.begin() );
    // b == TRUE

    QValueList<int> list;
    list.push_back( 100 );
    list.push_back( 200 );
    list.push_back( 300 );
    QTextOStream str( stdout );
    qCopy( list.begin(), list.end(), QTextOStreamIterator(str) );

    QValueVector<int> vec(3);
    vec.push_back( 100 );
    vec.push_back( 200 );
    vec.push_back( 300 );
    QValueVector<int> another;
    qCopyBackward( vec.begin(), vec.end(), another.begin() );
    // 'another' now contains 100, 200, 300
    // however the elements are copied one at a time 
    // in reverse order (300, 200, then 100)

    QStringList list1, list2;
    list1 << "Weis" << "Ettrich" << "Arnt" << "Sue";
    list2 << "Torben" << "Matthias";
    qCopy( list2.begin(), list2.end(), list1.begin() );

    QValueVector<QString> vec( list1.size(), "Dave" );
    qCopy( list2.begin(), list2.end(), vec.begin() );

    int arr[] = { 100, 200, 300 };
    QTextOStream str( stdout );
    qCopy( arr, arr + 3, QTextOStreamIterator( str ) ); 

    QDataStream str(...);
    QValueList<QRect> list;
    // ... fill the list here
    str << list;

    QValueList<QRect> list;
    str >> list;