Question

QPtrList类是一个提供双向链表的模板类。 详情请见……

#include <qptrlist.h>

继承了QPtrCollection。

被QObjectList、QSortedList和QStrList继承。

所有成员函数的列表。

公有成员

• QPtrList ()
• QPtrList ( constQPtrList<type>&list )
• ~QPtrList ()
• QPtrList<type> & operator= ( constQPtrList<type>&list )
• bool operator== ( constQPtrList<type>&list ) const
• virtual uint count () const
• bool isEmpty () const
• bool insert ( uintindex, consttype*item )
• void inSort ( consttype*item )
• void prepend ( consttype*item )
• void append ( consttype*item )
• bool remove ( uintindex )
• bool remove ()
• bool remove ( consttype*item )
• bool removeRef ( consttype*item )
• void removeNode ( QLNode*node )
• bool removeFirst ()
• bool removeLast ()
• type * take ( uintindex )
• type * take ()
• type * takeNode ( QLNode*node )
• virtual void clear ()
• void sort ()
• int find ( consttype*item )
• int findNext ( consttype*item )
• int findRef ( consttype*item )
• int findNextRef ( consttype*item )
• uint contains ( consttype*item ) const
• uint containsRef ( consttype*item ) const
• type * at ( uintindex )
• int at () const
• type * current () const
• QLNode * currentNode () const
• type * getFirst () const
• type * getLast () const
• type * first ()
• type * last ()
• type * next ()
• type * prev ()
• void toVector ( QGVector*vec ) const

重要的继承成员

• bool autoDelete () const
• void setAutoDelete ( boolenable )

保护成员

• virtual int compareItems ( QPtrCollection::Itemitem1, QPtrCollection::Itemitem2 )
• virtual QDataStream & read ( QDataStream&s, QPtrCollection::Item&item )
• virtual QDataStream & write ( QDataStream&s, QPtrCollection::Itemitem ) const

---

详细描述

QPtrList类是一个提供双向链表的模板类。

QValueList是可以替代这个类的的一个可兼容STL的的选择。

定义一个模板实例QPtrList<X>就创建了一个操作X（X*）指针的列表。

这个列表类是可以索引的并且有一个当前索引和一个当前项。第一项对应的是索引0。如果当前项为空，则当前索引为-1。

使用prepend()、insert()或append()可以插入项。可以使用remove()、removeRef()、removeFirst()和removeLast()来移除项。你可以使用find()、findNext()、findRef()或findNextRef()来搜索一个项。列表可以使用sort()来排序。你可以使用contains()或containsRef()来得到一个项出现的次数。你也可以使用current()来得到指向当前项的指针，用at()来得到一个在特定索引位置的项的指针，用getFirst()和getLast()来得到第一个或最后一个项的指针。你也可以使用first()、last()、next()和prev()（它们都会更新current()）来遍历列表。列表的删除属性可以用setAutoDelete()来设置。

实例：

    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;
    };

    QPtrList<Employee> list;
    list.setAutoDelete( TRUE ); // list列表拥有了这个对象

    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;

    // 对于非常大的列表是很没有效率的
    for ( uint i = 0; i < list.count(); ++i )
        if ( list.at(i) )
            cout << list.at( i )->surname().latin1() << endl;
  

输出是

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

    Doe
    Williams
    Jones
  

QPtrList有几个函数可以遍历列表，但是使用QPtrListIterator会更实用。多重列表的迭代器也可以遍历同一个列表，它们之间以及和当前列表项无关。

在上面的例子中，我们调用setAutoDelete(TRUE)使自动删除生效就是说列表在移除项的时候一起删除它。默认选项是当它们被移除的时候不被删除，但是我们的例子中对没有列表项没有其它的引用，所以如果不这么做的话会导致内存泄漏。

列表项被作为void*存储在内部的QLNode终了，它也保存指向前一个和后一个列表项的指针。currentNode()、removeNode()和takeNode()函数可以直接操作QLNode，但是必须仔细使用它们。节点的数据部分可以使用QLNode::getData()得到。

当向列表插入一个项的时候，只有指针被复制，而不是项自身，比如，我们做了一个浅复制。当一个项被插入时，也是可以让列表复制这个项的所有数据（深复制）。insert()、inSort()和append()在项被插入时调用虚函数QPtrCollection::newItem()。如果你想深复制，请继承这个列表并重新实现它。

当从列表中移除一个项时，虚函数QPtrCollection::deleteItem()被调用。QPtrList的默认实现是如果自动删除生效，就删除这个项。

虚函数compareItems()可以被重新实现用来比较两个列表项。这个函数被所有需要比较列表项的列表函数调用，比如remove(const type*)。如果你只想处理指针，又可以替代比较指针的函数，比如removeRef(const type*)。这些函数比那些调用compareItems()的稍微快些。

qstrlist.h中定义的QStrList是一个char*的列表。它重新实现了newItem()、deleteItem()和compareItems()。

也可以参考QPtrListIterator、集合类和非GUI类。

---

成员函数文档

QPtrList::QPtrList ()

构造一个空的列表。

QPtrList::QPtrList ( constQPtrList<type>&list )

构造一个list的复制。

list的每一个项都被添加到这个列表中。只有指针被复制（浅复制）。

QPtrList::~QPtrList ()

移除列表中的所有项并且销毁这个列表。

访问这个列表的所有列表迭代器都会被重置。

也可以参考setAutoDelete()。

void QPtrList::append ( consttype*item )

在列表的最后插入item。

被插入的项变为当前列表项。这和insert( count(), item )是相同的。

item必须不是一个空指针。

也可以参考insert()、current()和prepend()。

实例：customlayout/border.cpp、customlayout/card.cpp、customlayout/flow.cpp、grapher/grapher.cpp、listviews/listviews.cpp、listviews/listviews.h和qwerty/qwerty.cpp。

type * QPtrList::at ( uintindex )

返回一个在列表index位置的项的指针，如果索引超出范围，返回空。

如果index有效，设置这个项为当前列表项。有效范围是0……(count() - 1)。

这个函数是非常有效的。它从第一项、最后一项或当前项中最接近index的开始扫描。

也可以参考current()。

实例：customlayout/border.cpp、customlayout/card.cpp、customlayout/flow.cpp、dirview/dirview.cpp、fileiconview/qfileiconview.cpp、mdi/application.cpp和qwerty/qwerty.cpp。

int QPtrList::at () const

这是一个重载成员函数，提供了方便。它的行为基本上和上面的函数相同。

返回当前列表项的索引。如果当前项为空，返回值为-1。

也可以参考current()。

bool QPtrCollection::autoDelete () const

返回自动删除选项的设置。默认为假。

也可以参考setAutoDelete()。

void QPtrList::clear () [虚]

移除列表中所有项。

如果自动删除生效，被移除的项目将被删除。

所有访问这个列表的列表迭代器都将被重置。

也可以参考remove()、take()和setAutoDelete()。

从QPtrCollection中重新实现。

int QPtrList::compareItems ( QPtrCollection::Itemitem1, QPtrCollection::Itemitem2 ) [虚 保护]

这个虚函数比较两个列表项。

返回：

• 如果item1==item2，返回0
• 如果item1!=item2，返回非0

这个函数返回int而不是bool，这样可以重新实现返回三个值并且使用它来排序：

• 如果item1 == item2，返回0
• 如果item1>item2，返回>0（正整数）
• 如果item1<item2，返回<0（负整数）

inSort()需要compareItems()像这里所描述的这样来被实现。

这个函数不应该修改列表，因为一些常量函数调用compareItems()。

默认实现是比较指针。

uint QPtrList::contains ( consttype*item ) const

计算并且返回item在列表中出现的次数。

当在列表中搜索item时，compareItems()函数被调用。如果compareItems()没有被重新实现，调用containsRef()是更有效率的。

这个函数不影响当前列表项。

也可以参考containsRef()和compareItems()。

uint QPtrList::containsRef ( consttype*item ) const

计算并且返回item在列表中出现的次数。

调用这个函数比contains()快多了，因为contains()使用compareItems()来用item与列表中的每一个项进行比较。这个函数只比较指针。

这个函数不影响当前列表项。

也可以参考contains()。

uint QPtrList::count () const [虚]

返回列表中项的数量。

也可以参考isEmpty()。

实例：customlayout/border.cpp、customlayout/card.cpp、customlayout/flow.cpp、fileiconview/qfileiconview.cpp、grapher/grapher.cpp、mdi/application.cpp和qwerty/qwerty.cpp。

从QPtrCollection中重新实现的。

type * QPtrList::current () const

返回一个指向当前列表项的指针。当前列表项可能为空（意味着当前索引为-1）。

也可以参考at()。

QLNode * QPtrList::currentNode () const

返回指向当前列表节点的指针。

节点可以被保存并且稍后使用removeNode()移除。这样做的优点是可以直接移除这个项，而不用搜索列表。

警告：不要调用这个函数，除非你是专家。

也可以参考removeNode()、takeNode()和current()。

int QPtrList::find ( consttype*item )

找到item在列表中第一次出现的位置。

如果这个项被找到，列表会设置当前项指向找到的项，并且返回这个项的索引。如果没有被找到，列表设置当前项为空，当前索引为-1，并且返回-1。

当在列表中搜索这个项时，compareItems()函数被调用。如果compareItems()没有被重新实现，调用findRef()是更有效率的。

也可以参考findNext()、findRef()、compareItems()和current()。

int QPtrList::findNext ( consttype*item )

从当前列表项，找到item在列表中下一次出现的位置。

如果这个项被找到，列表会设置当前项指向找到的项，并且返回这个项的索引。如果没有被找到，列表设置当前项为空，当前索引为-1，并且返回-1。

当在列表中搜索这个项时，compareItems()函数被调用。如果compareItems()没有被重新实现，调用findNextRef()是更有效率的。

也可以参考find()、findNextRef()、compareItems()和current()。

int QPtrList::findNextRef ( consttype*item )

从当前列表项，找到item在列表中下一次出现的位置。

如果这个项被找到，列表会设置当前项指向找到的项，并且返回这个项的索引。如果没有被找到，列表设置当前项为空，当前索引为-1，并且返回-1。

调用这个函数比findNext()快得多，因为findNext()是使用compareItems()来用item与列表中的每一个项进行比较。这个函数只比较指针。

也可以参考findRef()、findNext()和current()。

int QPtrList::findRef ( consttype*item )

找到item在列表中第一次出现的位置。

如果这个项被找到，列表会设置当前项指向找到的项，并且返回这个项的索引。如果没有被找到，列表设置当前项为空，当前索引为-1，并且返回-1。

调用这个函数比find()快得多，因为find()是使用compareItems()来用item与列表中的每一个项进行比较。这个函数只比较指针。

也可以参考findNextRef()、find()和current()。

type * QPtrList::first ()

返回指向列表中第一个项的指针并且使它成为当前列表项，或者如果列表为空当前项就为空。

也可以参考getFirst()、last()、next()、prev()和current()。

实例：grapher/grapher.cpp、listviews/listviews.h和showimg/showimg.cpp。

type * QPtrList::getFirst () const

返回指向列表中第一个项的指针，如果列表为空返回空。

这个函数不影响当前列表项。

也可以参考first()和getLast()。

type * QPtrList::getLast () const

Returns a pointer to the last item in the list, or null if the list is empty. 返回指向列表中最后一个项的指针，如果列表为空返回空。

这个函数不影响当前列表项。

也可以参考last()和getFirst()。

void QPtrList::inSort ( consttype*item )

把item插入到列表中它被排序的位置。

排序依靠的是虚函数compareItems()。为了维护这个派逊，所有的项都必须使用inSort()来插入。

被插入的项变为当前项。

item必须不能是一个空指针。

请注意inSort()很慢。如果你想先向列表插入很多项，插入完之后再排序，你应该使用sort()。inSort()进行了O(n)次比较。这就意味着插入n个项到你的列表需要比较O(n^2)次，而sort()做同样的工作只需要O(n*log n)次。所以只有在你有一个预先排好序的列表并且想向其中插入少量的项时，再使用inSort()。

也可以参考insert()、compareItems()、current()和sort()。

bool QPtrList::insert ( uintindex, consttype*item )

插入item到列表的index位置。

如果成功返回真，或者如果index超出范围返回假。有效的范围是从0到count()（包括count()）。如果index==count()，项就被添加。

被插入的项变为当前项。

item必须不能是一个空指针。

也可以参考append()和current()。

bool QPtrList::isEmpty () const

如果列表是空的，返回真，否则返回假。

也可以参考count()。

type * QPtrList::last ()

返回指向列表最后一项的指针，并且把这一项变为当前列表项，如果列表为空，当前列表项为空。

也可以参考getLast()、first()、next()、prev()和current()。

type * QPtrList::next ()

返回指向当前项的下一项的指针。如果当前项为空或者它是最后一项，返回空。

把下一项作为当前项。如果当前项在这次函数调用之前就是最后一项了，当前项将被设置为空。如果当前项为空，这个函数就什么都不做。

也可以参考first()、last()、prev()和current()。

实例：grapher/grapher.cpp、listviews/listviews.h和showimg/showimg.cpp。

QPtrList<type>& QPtrList::operator= ( constQPtrList<type>&list )

把list赋值给这个列表并且返回这个列表的引用。

这个列表首先被清空，然后list中的每个项都被添加到这个列表中。只有指针被复制（浅复制），除非newItem()被重新实现了。

bool QPtrList::operator== ( constQPtrList<type>&list ) const

把这个列表和list进行比较。如果这个列表包含相同的数据，返回真，否则返回假。

void QPtrList::prepend ( consttype*item )

在列表开始的位置插入item。

被插入项变为当前列表项。这和insert( 0, item )是相同的。

item必须不能是一个空指针。

也可以参考append()、insert()和current()。

type * QPtrList::prev ()

返回指向当前项的前一个项的指针。如果当前项为空或者等于第一项，返回空。

把前一项作为当前项。如果当前项在这次函数调用之前就是第一项了，当前项被设置为空。如果当前项为空，这个函数就什么都不做。

也可以参考first()、last()、next()和current()。

QDataStream& QPtrList::read ( QDataStream&s, QPtrCollection::Item&item ) [虚 保护]

从流s中读取一个列表项并且返回流的引用。

默认实习是设置item为0。

也可以参考write()。

bool QPtrList::remove ( uintindex )

移除列表中index位置的项。

如果成功返回真，或者如果index超出范围返回假。有效范围是0……(count() - 1)（包括count()-1）。

如果自动删除生效，被移除的项目将被删除。

如果被移除的项不是列表中最后一项，被移除的项之后的项变为新的当前列表项。如果最后一项被移除，新的最后一项变为当前项。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考take()、clear()、setAutoDelete()、current()和removeRef()。

bool QPtrList::remove ()

这是一个重载成员函数，提供了方便。它的行为基本上和上面的函数相同。

移除当前列表项。

如果成功返回真，或者如果当前项为空，返回假。

如果自动删除生效，被移除的项目将被删除。

如果被移除的项不是列表中最后一项，被移除的项之后的项变为新的当前列表项。如果最后一项被移除，新的最后一项变为当前项。如果列表为空，当前项为空。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考take()、clear()、setAutoDelete()、current()和removeRef()。

bool QPtrList::remove ( consttype*item )

这是一个重载成员函数，提供了方便。它的行为基本上和上面的函数相同。

移除列表中第一次出现的item。

如果成功返回真，或者如果当前项为空，返回假。

如果自动删除生效，被移除的项目将被删除。

当在列表中搜索这个项的时候，compareItems()函数被调用。如果compareItems()没有被重新实现，调用removeRef()是更加有效率的。

如果被移除的项不是列表中最后一项，被移除的项之后的项变为新的当前列表项。如果最后一项被移除，新的最后一项变为当前项。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考removeRef()、take()、clear()、setAutoDelete()、compareItems()和current()。

bool QPtrList::removeFirst ()

移除列表中的第一项。如果成功返回真，或者如果列表是空的返回假。

如果自动删除生效，被移除的项目将被删除。

列表中的第一项变为新的当前列表项。如果列表变空了，当前列表项被设置为空。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考removeLast()、setAutoDelete()、current()和remove()。

bool QPtrList::removeLast ()

移除列表中的最后一项。如果成功返回真，或者如果列表是空的返回假。

如果自动删除生效，被移除的项目将被删除。

列表中的最后一项变为新的当前列表项。如果列表变空了，当前列表项被设置为空。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考removeFirst()、setAutoDelete()和current()。

void QPtrList::removeNode ( QLNode*node )

移除列表中的node节点。

这个节点必须存在于列表中，否则程序可能会崩溃。

如果自动删除生效，被移除的项目将被删除。

列表中的第一项变为新的当前列表项。如果列表变空了，当前列表项被设置为空。

所有指向被移除的列表迭代器都被指向这项的下一项或者如果被移除的项是最后一项，则指向它的前一项。

警告：不要调用这个函数，除非你是专家。

也可以参考takeNode()、currentNode()、remove()和removeRef()。

bool QPtrList::removeRef ( consttype*item )

移除列表中第一次出现的item。

如果成功返回真，或者如果这个项在列表中没有被找到，返回假。

如果自动删除生效，被移除的项目将被删除。

列表一直被扫描，直到指针item被找到为止。如果它被发现，它就会被移除。

等价于：

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

如果被移除的项不是列表中最后一项，被移除的项之后的项变为新的当前列表项。如果最后一项被移除，新的最后一项变为当前项。如果列表变空了，当前列表项被设置为空。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考remove()、clear()、setAutoDelete()和current()。

void QPtrCollection::setAutoDelete ( boolenable )

如果enable为真，设置集合可以自动删除它的内容，并且如果enable为假，就永远不能删除它们。

如果自动删除被打开，当集合本身被删除的时候，集合内所有的项也都被删除。如果只有这个集合指向它的项时，这个方法很方便。

为了安全，默认设置是假。如果你把它打开，对于集合的复制你要注意些——你自己也许会发现两个集合删除同一个项。

注意在子类中自动删除设置也许会影响其它函数。例如，一个有remove()函数的子类将会从它的数据结构中移除这个项，并且如果自动删除生效，也将会删除这个项。

也可以参考autoDelete().

实例：grapher/grapher.cpp、scribble/scribble.cpp和table/bigtable/main.cpp。

void QPtrList::sort ()

使用虚函数compareItems()的结果排序这个列表。

排序中使用堆排序算法。它对n项排序需要O(n*log n)次比较。这是排序问题中接近最佳的解决方案。

如果你的列表中的项支持操作符<和操作符==，你最好离开QSortedList，因为它使用这两个操作符为你实现了compareItems()函数。

也可以参考inSort()。

type * QPtrList::take ( uintindex )

把列表中在index位置的项拿出来，而不删除它（尽管如果自动删除是生效的。）

返回指向你从列表中拿出的项的指针，或者如果索引超出范围，返回空。有效范围是0..(count() - 1)（包括count()-1）。

如果被移除的项不是列表中最后一项，被移除的项之后的项变为新的当前列表项。如果最后一项被移除，新的最后一项变为当前项。如果列表变空了，当前列表项被设置为空。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考remove()、clear()和current()。

实例：customlayout/border.cpp、customlayout/card.cpp和customlayout/flow.cpp。

type * QPtrList::take ()

这是一个重载成员函数，提供了方便。它的行为基本上和上面的函数相同。

把列表中在index位置的项拿出来，而不删除它（尽管如果自动删除是生效的。）

返回指向你从列表中拿出的项的指针，或者如果索引超出范围，返回空。有效范围是0..(count() - 1)（包括count()-1）。

如果被移除的项不是列表中最后一项，被移除的项之后的项变为新的当前列表项。如果最后一项被移除，新的最后一项变为当前项。如果列表变空了，当前列表项被设置为空。

所有指向被移除项的列表迭代器都将会被指向新的当前项。

也可以参考remove()、clear()和current()。

type * QPtrList::takeNode ( QLNode*node )

把列表中的节点node拿出来，而不删除它（尽管如果自动删除是生效的。）返回指向你从列表中拿出的项的指针。

这个节点必须存在于列表中，否则程序可能会崩溃。

列表中的第一项变为新的当前列表项。如果列表变空了，当前列表项被设置为空。

所有指向被移除的列表迭代器都被指向这项的下一项或者如果被移除的项是最后一项，则指向它的前一项。

警告：不要调用这个函数，除非你是专家。

也可以参考removeNode()和currentNode()。

void QPtrList::toVector ( QGVector*vec ) const

存储所有的列表项到矢量vec中。

矢量必须和项的类型相同，否则结果将会是不确定的。

QDataStream& QPtrList::write ( QDataStream&s, QPtrCollection::Itemitem ) const [虚 保护]

写一个列表项item到流s中并且返回流的引用。

默认实现是不做任何事。

也可以参考read().