From d796c9dd933ab96ec83b9a634feedd5d32e1ba3f Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Tue, 8 Nov 2011 12:31:36 -0600 Subject: Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731 --- doc/html/qvaluelist.html | 785 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 785 insertions(+) create mode 100644 doc/html/qvaluelist.html (limited to 'doc/html/qvaluelist.html') diff --git a/doc/html/qvaluelist.html b/doc/html/qvaluelist.html new file mode 100644 index 000000000..8407b3dd2 --- /dev/null +++ b/doc/html/qvaluelist.html @@ -0,0 +1,785 @@ + + + + + +TQValueList Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

TQValueList Class Reference

+ +

The TQValueList class is a value-based template class that +provides lists. +More... +

All the functions in this class are reentrant when TQt is built with thread support.

+

#include <qvaluelist.h> +

Inherited by TQCanvasItemList, TQStringList, and TQValueStack. +

List of all member functions. +

Public Members

+ +

Related Functions

+ +

Detailed Description

+ + +The TQValueList class is a value-based template class that +provides lists. +

+ + + + +

TQValueList is a TQt implementation of an STL-like list container. +It can be used in your application if the standard list is not +available for your target platform(s). TQValueList is part of the +TQt Template Library. +

TQValueList<T> defines a template instance to create a list of +values that all have the class T. Note that TQValueList does not +store pointers to the members of the list; it holds a copy of +every member. This is why these kinds of classes are called "value +based"; TQPtrList and TQDict are "pointer based". +

TQValueList contains and manages a collection of objects of type T +and provides iterators that allow the contained objects to be +addressed. TQValueList owns the contained items. For more relaxed +ownership semantics, see TQPtrCollection and friends which are +pointer-based containers. +

Some classes cannot be used within a TQValueList, for example, all +classes derived from TQObject and thus all classes that implement +widgets. Only values can be used in a TQValueList. To qualify as a +value the class must provide: +

+

Note that C++ defaults to field-by-field assignment operators and +copy constructors if no explicit version is supplied. In many +cases this is sufficient. +

In addition, some compilers (e.g. Sun CC) might retquire that the +class provides an equality operator (operator==()). +

TQValueList's function naming is consistent with the other TQt +classes (e.g. count(), isEmpty()). TQValueList also provides extra +functions for compatibility with STL algorithms, such as size() +and empty(). Programmers already familiar with the STL list may +prefer to use the STL-compatible functions. +

Example: +

+    class Employee
+    {
+    public:
+        Employee(): sn(0) {}
+        Employee( const TQString& forename, const TQString& surname, int salary )
+            : fn(forename), sn(surname), sal(salary)
+        {}
+
+        TQString forename() const { return fn; }
+        TQString surname() const { return sn; }
+        int salary() const { return sal; }
+        void setSalary( int salary ) { sal = salary; }
+
+    private:
+        TQString fn;
+        TQString sn;
+        int sal;
+    };
+
+    typedef TQValueList<Employee> EmployeeList;
+    EmployeeList list;
+
+    list.append( Employee("John", "Doe", 50000) );
+    list.append( Employee("Jane", "Williams", 80000) );
+    list.append( Employee("Tom", "Jones", 60000) );
+
+    Employee mary( "Mary", "Hawthorne", 90000 );
+    list.append( mary );
+    mary.setSalary( 100000 );
+
+    EmployeeList::iterator it;
+    for ( it = list.begin(); it != list.end(); ++it )
+        cout << (*it).surname().latin1() << ", " <<
+                (*it).forename().latin1() << " earns " <<
+                (*it).salary() << endl;
+
+    // Output:
+    // Doe, John earns 50000
+    // Williams, Jane earns 80000
+    // Hawthorne, Mary earns 90000
+    // Jones, Tom earns 60000
+
+ +

Notice that the latest changes to Mary's salary did not affect the +value in the list because the list created a copy of Mary's entry. +

There are several ways to find items in the list. The begin() and +end() functions return iterators to the beginning and end of the +list. The advantage of getting an iterator is that you can move +forward or backward from this position by +incrementing/decrementing the iterator. The iterator returned by +end() points to the item which is one past the last item in the +container. The past-the-end iterator is still associated with the +list it belongs to, however it is not dereferenceable; +operator*() will not return a well-defined value. If the list is +empty(), the iterator returned by begin() will equal the iterator +returned by end(). +

Another way to find an item in the list is by using the qFind() algorithm. For example: +

+    TQValueList<int> list;
+    ...
+    TQValueList<int>::iterator it = qFind( list.begin(), list.end(), 3 );
+    if ( it != list.end() )
+        // it points to the found item
+
+ +

It is safe to have multiple iterators a the list at the same +time. If some member of the list is removed, only iterators +pointing to the removed member become invalid. Inserting into the +list does not invalidate any iterator. For convenience, the +function last() returns a reference to the last item in the list, +and first() returns a reference to the the first item. If the +list is empty(), both last() and first() have undefined behavior +(your application will crash or do unpredictable things). Use +last() and first() with caution, for example: +

+    TQValueList<int> list;
+    list.append( 1 );
+    list.append( 2 );
+    list.append( 3 );
+    ...
+    if ( !list.empty() ) {
+        // OK, modify the first item
+        int& i = list.first();
+        i = 18;
+    }
+    ...
+    TQValueList<double> dlist;
+    double d = dlist.last(); // undefined
+
+ +

Because TQValueList is value-based there is no need to be careful +about deleting items in the list. The list holds its own copies +and will free them if the corresponding member or the list itself +is deleted. You can force the list to free all of its items with +clear(). +

TQValueList is shared implicitly, which means it can be copied in +constant time, i.e. O(1). If multiple TQValueList instances share +the same data and one needs to modify its contents, this modifying +instance makes a copy and modifies its private copy; therefore it +does not affect the other instances; this takes O(n) time. This is +often called "copy on write". If a TQValueList is being used in a +multi-threaded program, you must protect all access to the list. +See TQMutex. +

There are several ways to insert items into the list. The +prepend() and append() functions insert items at the beginning and +the end of the list respectively. The insert() function comes in +several flavors and can be used to add one or more items at +specific positions within the list. +

Items can also be removed from the list in several ways. There +are several variants of the remove() function, which removes a +specific item from the list. The remove() function will find and +remove items according to a specific item value. +

Lists can also be sorted using the TQt Template + Library. For example with qHeapSort(): +

Example: +

+    TQValueList<int> list;
+    list.append( 5 );
+    list.append( 8 );
+    list.append( 3 );
+    list.append( 4 );
+    qHeapSort( list );
+
+ +

See also TQValueListIterator, TQt Template Library Classes, Implicitly and Explicitly Shared Classes, and Non-GUI Classes. + +

Member Type Documentation

+

TQValueList::ConstIterator

+ +

This iterator is an instantiation of TQValueListConstIterator for +the same type as this TQValueList. In other words, if you +instantiate TQValueList, ConstIterator is a +TQValueListConstIterator. Several member function use it, such +as TQValueList::begin(), which returns an iterator pointing to the +first item in the list. +

Functionally, this is almost the same as Iterator. The only +difference is you cannot use ConstIterator for non-const +operations, and that the compiler can often generate better code +if you use ConstIterator. +

See also TQValueListIterator and Iterator. + +

TQValueList::Iterator

+ +

This iterator is an instantiation of TQValueListIterator for the +same type as this TQValueList. In other words, if you instantiate +TQValueList, Iterator is a TQValueListIterator. Several +member function use it, such as TQValueList::begin(), which returns +an iterator pointing to the first item in the list. +

Functionally, this is almost the same as ConstIterator. The only +difference is that you cannot use ConstIterator for non-const +operations, and that the compiler can often generate better code +if you use ConstIterator. +

See also TQValueListIterator and ConstIterator. + +

TQValueList::const_iterator

+The list's const iterator type, TQValueListConstIterator. +

TQValueList::const_pointer

+The const pointer to T type. +

TQValueList::const_reference

+The const reference to T type. +

TQValueList::iterator

+The list's iterator type, TQValueListIterator. +

TQValueList::pointer

+The pointer to T type. +

TQValueList::reference

+The reference to T type. +

TQValueList::size_type

+An unsigned integral type, used to represent various sizes. +

TQValueList::value_type

+The type of the object stored in the list, T. +

Member Function Documentation

+

TQValueList::TQValueList () +

+ +

Constructs an empty list. + +

TQValueList::TQValueList ( const TQValueList<T> & l ) +

+ +

Constructs a copy of l. +

This operation takes O(1) time because TQValueList is implicitly shared. +

The first modification to a list will take O(n) time. + +

TQValueList::TQValueList ( const std::list<T> & l ) +

+ +

Contructs a copy of l. +

This constructor is provided for compatibility with STL +containers. + +

TQValueList::~TQValueList () +

+ +

Destroys the list. References to the values in the list and all +iterators of this list become invalidated. Note that it is +impossible for an iterator to check whether or not it is valid: +TQValueList is highly tuned for performance, not for error +checking. + +

iterator TQValueList::append ( const T & x ) +

+ +

Inserts x at the end of the list. +

See also insert() and prepend(). + +

Examples: checklists/checklists.cpp and fonts/simple-qfont-demo/viewer.cpp. +

const_iterator TQValueList::at ( size_type i ) const +

+ +

Returns an iterator pointing to the item at position i in the +list, or an undefined value if the index is out of range. +

Warning: This function uses a linear search and can be extremely +slow for large lists. TQValueList is not optimized for random item +access. If you need random access use a different container, such +as TQValueVector. + +

iterator TQValueList::at ( size_type i ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an iterator pointing to the item at position i in the +list, or an undefined value if the index is out of range. +

+

reference TQValueList::back () +

+ +

Returns a reference to the last item. If the list contains no last +item (i.e. empty() returns TRUE), the return value is undefined. +

This function is provided for STL compatibility. It is equivalent +to last(). +

See also front(). + +

const_reference TQValueList::back () const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

+

const_iterator TQValueList::begin () const +

+ +

Returns an iterator pointing to the first item in the list. This +iterator equals end() if the list is empty. +

See also first(), end(), and constBegin(). + +

Examples: canvas/canvas.cpp, chart/canvasview.cpp, chart/element.cpp, checklists/checklists.cpp, sql/overview/insert/main.cpp, table/statistics/statistics.cpp, and themes/themes.cpp. +

iterator TQValueList::begin () +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an iterator pointing to the first item in the list. This +iterator equals end() if the list is empty. +

See also first() and end(). + +

void TQValueList::clear () +

+ +

Removes all items from the list. +

See also remove(). + +

const_iterator TQValueList::constBegin () const +

+ +

Returns an iterator pointing to the first item in the list. This +iterator equals constEnd() if the list is empty. +

See also begin(). + +

const_iterator TQValueList::constEnd () const +

+ +

Returns an iterator pointing past the last item in the list. +This iterator equals constBegin() if the list is empty. +

See also end(). + +

size_type TQValueList::contains ( const T & x ) const +

+ +

Returns the number of occurrences of the value x in the list. + +

size_type TQValueList::count () const +

+ +

Returns the number of items in the list. +

See also isEmpty(). + +

Examples: chart/element.cpp, fileiconview/qfileiconview.cpp, and table/statistics/statistics.cpp. +

bool TQValueList::empty () const +

+ +

Returns TRUE if the list contains no items; otherwise returns +FALSE. +

See also size(). + +

iterator TQValueList::end () +

+ +

Returns an iterator pointing past the last item in the list. +This iterator equals begin() if the list is empty. +

See also last(), begin(), and constEnd(). + +

Examples: canvas/canvas.cpp, chart/canvasview.cpp, chart/element.cpp, checklists/checklists.cpp, sql/overview/insert/main.cpp, table/statistics/statistics.cpp, and themes/themes.cpp. +

const_iterator TQValueList::end () const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an iterator pointing past the last item in the list. +This iterator equals begin() if the list is empty. +

See also last() and begin(). + +

iterator TQValueList::erase ( iterator it ) +

+ +

Removes the item pointed to by it from the list. No iterators +other than it or other iterators pointing at the same item as +it are invalidated. Returns an iterator to the next item after +it, or end() if there is no such item. +

This function is provided for STL compatibility. It is equivalent +to remove(). + +

iterator TQValueList::erase ( iterator first, iterator last ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Deletes all items from first to last (not including last). No iterators are invalidated, except those pointing to the +removed items themselves. Returns last. + +

iterator TQValueList::find ( const T & x ) +

+ +

Returns an iterator pointing to the first occurrence of x in +the list. +

Returns end() is no item matched. + +

const_iterator TQValueList::find ( const T & x ) const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an iterator pointing to the first occurrence of x in +the list. +

Returns end() if no item matched. + +

iterator TQValueList::find ( iterator it, const T & x ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Finds the first occurrence of x in the list starting at the +position given by it. +

Returns end() if no item matched. + +

const_iterator TQValueList::find ( const_iterator it, const T & x ) const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Finds the first occurrence of x in the list starting at the +position given by it. +

Returns end() if no item matched. + +

int TQValueList::findIndex ( const T & x ) const +

+ +

Returns the index of the first occurrence of the value x. +Returns -1 if no item matched. + +

T & TQValueList::first () +

+ +

Returns a reference to the first item. If the list contains no +first item (i.e. isEmpty() returns TRUE), the return value is +undefined. +

See also last(). + +

Example: network/mail/smtp.cpp. +

const T & TQValueList::first () const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

+

const_iterator TQValueList::fromLast () const +

+ +

Returns an iterator to the last item in the list, or end() if +there is no last item. +

Use the end() function instead. For example: +

+    TQValueList<int> l;
+    ...
+    TQValueList<int>::iterator it = l.end();
+    --it;
+    if ( it != end() )
+        // ...
+
+ +

+

iterator TQValueList::fromLast () +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns an iterator to the last item in the list, or end() if +there is no last item. +

Use the end() function instead. For example: +

+    TQValueList<int> l;
+    ...
+    TQValueList<int>::iterator it = l.end();
+    --it;
+    if ( it != end() )
+        // ...
+
+ +

+

reference TQValueList::front () +

+ +

Returns a reference to the first item. If the list contains no +first item (i.e. empty() returns TRUE), the return value is +undefined. +

This function is provided for STL compatibility. It is equivalent +to first(). +

See also back(). + +

const_reference TQValueList::front () const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

+

iterator TQValueList::insert ( iterator it, const T & x ) +

+ +

Inserts the value x in front of the item pointed to by the +iterator, it. +

Returns an iterator pointing at the inserted item. +

See also append() and prepend(). + +

Example: themes/themes.cpp. +

void TQValueList::insert ( iterator pos, size_type n, const T & x ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Inserts n copies of x before position pos. + +

bool TQValueList::isEmpty () const +

+ +

Returns TRUE if the list contains no items; otherwise returns +FALSE. +

See also count(). + +

Examples: fonts/simple-qfont-demo/viewer.cpp and network/mail/smtp.cpp. +

T & TQValueList::last () +

+ +

Returns a reference to the last item. If the list contains no last +item (i.e. empty() returns TRUE), the return value is undefined. + +

const T & TQValueList::last () const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

+

bool TQValueList::operator!= ( const TQValueList<T> & l ) const +

+ +

Compares both lists. +

Returns TRUE if this list and l are unequal; otherwise returns +FALSE. + +

TQValueList<T> TQValueList::operator+ ( const TQValueList<T> & l ) const +

+ +

Creates a new list and fills it with the items of this list. Then +the items of l are appended. Returns the new list. + +

TQValueList<T> & TQValueList::operator+= ( const TQValueList<T> & l ) +

+ +

Appends the items of l to this list. Returns a reference to +this list. + +

TQValueList<T> & TQValueList::operator+= ( const T & x ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Appends the value x to the list. Returns a reference to the +list. + +

TQValueList<T> & TQValueList::operator<< ( const T & x ) +

+ +

Adds the value x to the end of the list. +

Returns a reference to the list. + +

TQValueList<T> & TQValueList::operator= ( const TQValueList<T> & l ) +

+ +

Assigns l to this list and returns a reference to this list. +

All iterators of the current list become invalidated by this +operation. The cost of such an assignment is O(1) since TQValueList +is implicitly shared. + +

TQValueList<T> & TQValueList::operator= ( const std::list<T> & l ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Assigns the contents of l to the list. +

All iterators of the current list become invalidated by this +operation. + +

bool TQValueList::operator== ( const TQValueList<T> & l ) const +

+ +

Compares both lists. +

Returns TRUE if this list and l are equal; otherwise returns +FALSE. + +

bool TQValueList::operator== ( const std::list<T> & l ) const +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns TRUE if this list and l are equal; otherwise returns +FALSE. +

This operator is provided for compatibility with STL containers. + +

const T & TQValueList::operator[] ( size_type i ) const +

+ +

Returns a const reference to the item with index i in the list. +It is up to you to check whether this item really exists. You can +do that easily with the count() function. However this operator +does not check whether i is in range and will deliver undefined +results if it does not exist. +

Warning: This function uses a linear search and can be extremely +slow for large lists. TQValueList is not optimized for random item +access. If you need random access use a different container, such +as TQValueVector. + +

T & TQValueList::operator[] ( size_type i ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Returns a non-const reference to the item with index i. + +

void TQValueList::pop_back () +

+ +

Removes the last item. If there is no last item, this operation is +undefined. +

This function is provided for STL compatibility. + +

void TQValueList::pop_front () +

+ +

Removes the first item. If there is no first item, this operation +is undefined. +

This function is provided for STL compatibility. + +

iterator TQValueList::prepend ( const T & x ) +

+ +

Inserts x at the beginning of the list. +

See also insert() and append(). + +

void TQValueList::push_back ( const T & x ) +

+ +

Inserts x at the end of the list. +

This function is provided for STL compatibility. It is equivalent +to append(). + +

void TQValueList::push_front ( const T & x ) +

+ +

Inserts x at the beginning of the list. +

This function is provided for STL compatibility. It is equivalent +to prepend(). + +

Example: toplevel/options.ui.h. +

iterator TQValueList::remove ( iterator it ) +

+ +

Removes the item pointed to by it from the list. No iterators +other than it or other iterators pointing at the same item as +it are invalidated. Returns an iterator to the next item after +it, or end() if there is no such item. +

See also clear(). + +

uint TQValueList::remove ( const T & x ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

Removes all items that have value x and returns the number of +removed items. + +

size_type TQValueList::size () const +

+ +

Returns the number of items in the list. +

This function is provided for STL compatibility. It is equivalent +to count(). +

See also empty(). + +

Related Functions

+

TQDataStream & operator<< ( TQDataStream & s, const TQValueList<T> & l ) +

+ +

This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

+

Writes a list, l, to the stream s. The type T stored in the +list must implement the streaming operator. + +

TQDataStream & operator>> ( TQDataStream & s, TQValueList<T> & l ) +

+ +

+

Reads a list, l, from the stream s. The type T stored in the +list must implement the streaming operator. + + +

+This file is part of the TQt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
TQt 3.3.8
+
+ -- cgit v1.2.1