CopperSpice API  1.7.2
Generic Algorithms

QtAlgorithms header includes the generic, template-based algorithms. More...

Functions

template<typename Container >
void qDeleteAll (const Container &c)
 
template<typename ForwardIterator >
void qDeleteAll (ForwardIterator begin, ForwardIterator end)
 
template<typename T >
void qSwap (T &value1, T &value2)
 

Detailed Description

CopperSpice provides a number of global template functions in <QtAlgorithms> which work on containers and perform standard operations. These algorithms can be used with any container class that provide STL-style iterators including QList, QLinkedList, QVector, QFlatMap, QMap, and QHash.

Most algorithms take STL style iterators as parameters. The algorithms are generic in the sense that they are not bound to a specific iterator class. You can use them with iterators that meet a certain set of requirements.

Different algorithms can have different requirements for the iterators they accept. For example, std::fill() accepts two forward iterators. The iterator types required are specified for each algorithm. If an iterator of the wrong type is passed (for example, if QList::ConstIterator is passed as an output iterator) you will always get a compiler error, although not necessarily a very informative one.

Some algorithms have special requirements on the value type stored in the containers. For example, qDeleteAll() requires the value type is a non const pointer type. QWidget * is a valid type for qDeleteAll(). The value type requirements are specified for each algorithm and the compiler will produce an error if a requirement is not met.

Types of Iterators

The algorithms have certain requirements on the iterator types they accept and these are specified individually for each function. The compiler will produce an error if a requirement is not met.

Input Iterators

An input iterator is an iterator that can be used for reading data sequentially from a container. It must provide the following operators: == and != for comparing two iterators, unary * for retrieving the value stored in the item, and prefix ++ for advancing to the next item.

The CopperSpice container iterator types (const and non-const) are all input iterators.

Output Iterators

An output iterator is an iterator that can be used for writing data sequentially to a container or to some output stream. It must provide the following operators: unary * for writing a value (i.e., *it = val) and prefix ++ for advancing to the next item.

The CopperSpice container non-const iterator types are all output iterators.

Forward Iterators

A forward iterator is an iterator that meets the requirements of both input iterators and output iterators.

The CopperSpice container non-const iterator types are all forward iterators.

Bidirectional Iterators

A bidirectional iterator is an iterator that meets the requirements of forward iterators but that in addition supports prefix for iterating backward.

The CopperSpice containers' non-const iterator types are all bidirectional iterators.

Random Access Iterators

The last category which is random access iterators, is the most powerful type of iterator. It supports all the requirements of a bidirectional iterator, and supports the operations shown in the following table.

The iterators for QList and QVector are random access iterators.

i += n advances iterator i by n positions
i -= n moves iterator i back by n positions
i + n or n + i returns the iterator for the item n positions ahead of iterator i
i - n returns the iterator for the item n positions behind of iterator i
i - j returns the number of items between iterators i and j
i[n] same as *(i + n)
i < j returns true if iterator j comes after iterator i

STL Algorithms

The following table shows the CopperSpice algorithms which have been replaced by an STL algorithm.

CopperSpice Function STL Function
qBinaryFind std::binary_search or std::lower_bound
qCopy std::copy
qCopyBackward std::copy_backward
qCount std::count
qEqual std::equal
qFill std::fill
qFind std::find
qGreater std::greater
qLess std::less
qLowerBound std::lower_bound
qSort std::sort
qStableSort std::stable_sort
qUpperBound std::upper_bound
See also
container classes, <QGlobal>.

Function Documentation

template<typename Container >
void qDeleteAll ( const Container &  c)
inline

This is the same as qDeleteAll(c.begin(), c.end()).

template<typename ForwardIterator >
void qDeleteAll ( ForwardIterator  begin,
ForwardIterator  end 
)

Deletes all the items in the range from begin to end using the C++ delete operator. The item type must be a pointer type (for example, QWidget *).

list.append(new Employee("Blackpool", "Stephen"));
list.append(new Employee("Twist", "Oliver"));
qDeleteAll(list.begin(), list.end());
list.clear();

This function does not remove the items from the container, it merely calls delete on them. In the example above we call clear() on the container to remove the items.

This function can also be used to delete items stored in associative containers, such as QMap and QHash. Only the objects stored in each container will be deleted by this function, objects used as keys will not be deleted.

See also
forward iterators.
template<typename T >
void qSwap ( T &  value1,
T &  value2 
)
inline

Exchanges the values of variables value1 and value2.

double pi = 3.14;
double e = 2.71;
qSwap(pi, e); // pi == 2.71, e == 3.14