# QSet

The QSet class is a template class that provides a hash-table-based set. More...

` #include <QSet>`

**Note:** All functions in this class are reentrant.

## Public Types

class | const_iterator |

class | iterator |

typedef | ConstIterator |

typedef | Iterator |

typedef | const_pointer |

typedef | const_reference |

typedef | difference_type |

typedef | key_type |

typedef | pointer |

typedef | reference |

typedef | size_type |

typedef | value_type |

## Public Functions

QSet () | |

QSet ( const QSet<T> & other ) | |

const_iterator | begin () const |

iterator | begin () |

int | capacity () const |

void | clear () |

const_iterator | constBegin () const |

const_iterator | constEnd () const |

const_iterator | constFind ( const T & value ) const |

bool | contains ( const T & value ) const |

bool | contains ( const QSet<T> & other ) const |

int | count () const |

bool | empty () const |

const_iterator | end () const |

iterator | end () |

iterator | erase ( iterator pos ) |

const_iterator | find ( const T & value ) const |

iterator | find ( const T & value ) |

const_iterator | insert ( const T & value ) |

QSet<T> & | intersect ( const QSet<T> & other ) |

bool | isEmpty () const |

bool | remove ( const T & value ) |

void | reserve ( int size ) |

int | size () const |

void | squeeze () |

QSet<T> & | subtract ( const QSet<T> & other ) |

void | swap ( QSet<T> & other ) |

QList<T> | toList () const |

QSet<T> & | unite ( const QSet<T> & other ) |

QList<T> | values () const |

bool | operator!= ( const QSet<T> & other ) const |

QSet<T> | operator& ( const QSet<T> & other ) const |

QSet<T> & | operator&= ( const QSet<T> & other ) |

QSet<T> & | operator&= ( const T & value ) |

QSet<T> | operator+ ( const QSet<T> & other ) const |

QSet<T> & | operator+= ( const QSet<T> & other ) |

QSet<T> & | operator+= ( const T & value ) |

QSet<T> | operator- ( const QSet<T> & other ) const |

QSet<T> & | operator-= ( const QSet<T> & other ) |

QSet<T> & | operator-= ( const T & value ) |

QSet<T> & | operator<< ( const T & value ) |

QSet<T> & | operator= ( const QSet<T> & other ) |

bool | operator== ( const QSet<T> & other ) const |

QSet<T> | operator| ( const QSet<T> & other ) const |

QSet<T> & | operator|= ( const QSet<T> & other ) |

QSet<T> & | operator|= ( const T & value ) |

## Static Public Members

QSet<T> | fromList ( const QList<T> & list ) |

## Related Non-Members

QDataStream & | operator<< ( QDataStream & out, const QSet<T> & set ) |

QDataStream & | operator>> ( QDataStream & in, QSet<T> & set ) |

## Detailed Description

The QSet class is a template class that provides a hash-table-based set.

QSet<T> is one of Qt's generic container classes. It stores values in an unspecified order and provides very fast lookup of the values. Internally, QSet<T> is implemented as a QHash.

Here's an example QSet with QString values:

QSet<QString> set;

To insert a value into the set, use insert():

set.insert("one"); set.insert("three"); set.insert("seven");

Another way to insert items into the set is to use operator<<():

set << "twelve" << "fifteen" << "nineteen";

To test whether an item belongs to the set or not, use contains():

if (!set.contains("ninety-nine")) ...

If you want to navigate through all the values stored in a QSet, you can use an iterator. QSet supports both Java-style iterators (QSetIterator and QMutableSetIterator) and STL-style iterators (QSet::iterator and QSet::const_iterator). Here's how to iterate over a QSet<QWidget *> using a Java-style iterator:

QSetIterator<QWidget *> i(set); while (i.hasNext()) qDebug() << i.next();

Here's the same code, but using an STL-style iterator:

QSet<QWidget *>::const_iterator i = set.constBegin(); while (i != set.constEnd()) { qDebug() << *i; ++i; }

QSet is unordered, so an iterator's sequence cannot be assumed to be predictable. If ordering by key is required, use a QMap.

To navigate through a QSet, you can also use foreach:

QSet<QString> set; ... foreach (const QString &value, set) qDebug() << value;

Items can be removed from the set using remove(). There is also a clear() function that removes all items.

QSet's value data type must be an assignable data type. You cannot, for example, store a QWidget as a value; instead, store a QWidget *. In addition, the type must provide `operator==()`, and there must also be a global qHash() function that returns a hash value for an argument of the key's type. See the QHash documentation for a list of types supported by qHash().

Internally, QSet uses a hash table to perform lookups. The hash table automatically grows and shrinks to provide fast lookups without wasting memory. You can still control the size of the hash table by calling reserve(), if you already know approximately how many elements the QSet will contain, but this isn't necessary to obtain good performance. You can also call capacity() to retrieve the hash table's size.

**See also **QSetIterator, QMutableSetIterator, QHash, and QMap.

## Member Type Documentation

### typedef QSet::ConstIterator

Qt-style synonym for QSet::const_iterator.

### typedef QSet::Iterator

Qt-style synonym for QSet::iterator.

This typedef was introduced in Qt 4.2.

### typedef QSet::const_pointer

Typedef for const T *. Provided for STL compatibility.

### typedef QSet::const_reference

Typedef for const T &. Provided for STL compatibility.

### typedef QSet::difference_type

Typedef for const ptrdiff_t. Provided for STL compatibility.

### typedef QSet::key_type

Typedef for T. Provided for STL compatibility.

### typedef QSet::pointer

Typedef for T *. Provided for STL compatibility.

### typedef QSet::reference

Typedef for T &. Provided for STL compatibility.

### typedef QSet::size_type

Typedef for int. Provided for STL compatibility.

### typedef QSet::value_type

Typedef for T. Provided for STL compatibility.

## Member Function Documentation

### QSet::QSet ()

Constructs an empty set.

### QSet::QSet ( const QSet<T> & *other* )

Constructs a copy of *other*.

This operation occurs in constant time, because QSet is implicitly shared. This makes returning a QSet from a function very fast. If a shared instance is modified, it will be copied (copy-on-write), and this takes linear time.

**See also **operator=().

### const_iterator QSet::begin () const

Returns a const STL-style iterator positioned at the first item in the set.

**See also **constBegin() and end().

### iterator QSet::begin ()

This is an overloaded function.

Returns a non-const STL-style iterator positioned at the first item in the set.

This function was introduced in Qt 4.2.

### int QSet::capacity () const

Returns the number of buckets in the set's internal hash table.

The sole purpose of this function is to provide a means of fine tuning QSet's memory usage. In general, you will rarely ever need to call this function. If you want to know how many items are in the set, call size().

**See also **reserve() and squeeze().

### void QSet::clear ()

Removes all elements from the set.

### const_iterator QSet::constBegin () const

Returns a const STL-style iterator positioned at the first item in the set.

**See also **begin() and constEnd().

### const_iterator QSet::constEnd () const

Returns a const STL-style iterator pointing to the imaginary item after the last item in the set.

**See also **constBegin() and end().

### const_iterator QSet::constFind ( const T & *value* ) const

Returns a const iterator positioned at the item *value* in the set. If the set contains no item *value*, the function returns constEnd().

This function was introduced in Qt 4.2.

**See also **find() and contains().

### bool QSet::contains ( const T & *value* ) const

Returns true if the set contains item *value*; otherwise returns false.

**See also **insert(), remove(), and find().

### bool QSet::contains ( const QSet<T> & *other* ) const

Returns true if the set contains all items from the *other* set; otherwise returns false.

This function was introduced in Qt 4.6.

**See also **insert(), remove(), and find().

### int QSet::count () const

### bool QSet::empty () const

Returns true if the set is empty. This function is provided for STL compatibility. It is equivalent to isEmpty().

### const_iterator QSet::end () const

Returns a const STL-style iterator positioned at the imaginary item after the last item in the set.

**See also **constEnd() and begin().

### iterator QSet::end ()

This is an overloaded function.

Returns a non-const STL-style iterator pointing to the imaginary item after the last item in the set.

This function was introduced in Qt 4.2.

### iterator QSet::erase ( iterator *pos* )

Removes the item at the iterator position *pos* from the set, and returns an iterator positioned at the next item in the set.

Unlike remove(), this function never causes QSet to rehash its internal data structure. This means that it can safely be called while iterating, and won't affect the order of items in the set.

This function was introduced in Qt 4.2.

### const_iterator QSet::find ( const T & *value* ) const

Returns a const iterator positioned at the item *value* in the set. If the set contains no item *value*, the function returns constEnd().

This function was introduced in Qt 4.2.

**See also **constFind() and contains().

### iterator QSet::find ( const T & *value* )

This is an overloaded function.

Returns a non-const iterator positioned at the item *value* in the set. If the set contains no item *value*, the function returns end().

This function was introduced in Qt 4.2.

### QSet<T> QSet::fromList ( const QList<T> & *list* )` [static]`

Returns a new QSet object containing the data contained in *list*. Since QSet doesn't allow duplicates, the resulting QSet might be smaller than the *list*, because QList can contain duplicates.

Example:

QStringList list; list << "Julia" << "Mike" << "Mike" << "Julia" << "Julia"; QSet<QString> set = QSet<QString>::fromList(list); set.contains("Julia"); // returns true set.contains("Mike"); // returns true set.size(); // returns 2

**See also **toList() and QList::toSet().

### const_iterator QSet::insert ( const T & *value* )

Inserts item *value* into the set, if *value* isn't already in the set, and returns an iterator pointing at the inserted item.

**See also **operator<<(), remove(), and contains().

### QSet<T> & QSet::intersect ( const QSet<T> & *other* )

Removes all items from this set that are not contained in the *other* set. A reference to this set is returned.

**See also **operator&=(), unite(), and subtract().

### bool QSet::isEmpty () const

Returns true if the set contains no elements; otherwise returns false.

### bool QSet::remove ( const T & *value* )

Removes any occurrence of item *value* from the set. Returns true if an item was actually removed; otherwise returns false.

**See also **contains() and insert().

### void QSet::reserve ( int *size* )

Ensures that the set's internal hash table consists of at least *size* buckets.

This function is useful for code that needs to build a huge set and wants to avoid repeated reallocation. For example:

QSet<QString> set; set.reserve(20000); for (int i = 0; i < 20000; ++i) set.insert(values[i]);

Ideally, *size* should be slightly more than the maximum number of elements expected in the set. *size* doesn't have to be prime, because QSet will use a prime number internally anyway. If *size* is an underestimate, the worst that will happen is that the QSet will be a bit slower.

In general, you will rarely ever need to call this function. QSet's internal hash table automatically shrinks or grows to provide good performance without wasting too much memory.

**See also **squeeze() and capacity().

### int QSet::size () const

Returns the number of items in the set.

**See also **isEmpty() and count().

### void QSet::squeeze ()

Reduces the size of the set's internal hash table to save memory.

The sole purpose of this function is to provide a means of fine tuning QSet's memory usage. In general, you will rarely ever need to call this function.

**See also **reserve() and capacity().

### QSet<T> & QSet::subtract ( const QSet<T> & *other* )

Removes all items from this set that are contained in the *other* set. Returns a reference to this set.

**See also **operator-=(), unite(), and intersect().

### void QSet::swap ( QSet<T> & *other* )

Swaps set *other* with this set. This operation is very fast and never fails.

This function was introduced in Qt 4.8.

### QList<T> QSet::toList () const

Returns a new QList containing the elements in the set. The order of the elements in the QList is undefined.

Example:

QSet<QString> set; set << "red" << "green" << "blue" << ... << "black"; QList<QString> list = set.toList(); qSort(list);

**See also **fromList(), QList::fromSet(), and qSort().

### QSet<T> & QSet::unite ( const QSet<T> & *other* )

Each item in the *other* set that isn't already in this set is inserted into this set. A reference to this set is returned.

**See also **operator|=(), intersect(), and subtract().

### QList<T> QSet::values () const

Returns a new QList containing the elements in the set. The order of the elements in the QList is undefined.

This is the same as toList().

**See also **fromList(), QList::fromSet(), and qSort().

### bool QSet::operator!= ( const QSet<T> & *other* ) const

Returns true if the *other* set is not equal to this set; otherwise returns false.

Two sets are considered equal if they contain the same elements.

This function requires the value type to implement `operator==()`.

### QSet<T> QSet::operator& ( const QSet<T> & *other* ) const

Returns a new QSet that is the intersection of this set and the *other* set.

**See also **intersect(), operator&=(), operator|(), and operator-().

### QSet<T> & QSet::operator&= ( const QSet<T> & *other* )

Same as intersect(*other*).

**See also **operator&(), operator|=(), and operator-=().

### QSet<T> & QSet::operator&= ( const T & *value* )

This is an overloaded function.

Same as intersect(*other*), if we consider *other* to be a set that contains the singleton *value*.

### QSet<T> QSet::operator+ ( const QSet<T> & *other* ) const

Returns a new QSet that is the union of this set and the *other* set.

**See also **unite(), operator|=(), operator&(), and operator-().

### QSet<T> & QSet::operator+= ( const QSet<T> & *other* )

Same as unite(*other*).

**See also **operator|(), operator&=(), and operator-=().

### QSet<T> & QSet::operator+= ( const T & *value* )

Inserts a new item *value* and returns a reference to the set. If *value* already exists in the set, the set is left unchanged.

### QSet<T> QSet::operator- ( const QSet<T> & *other* ) const

Returns a new QSet that is the set difference of this set and the *other* set, i.e., this set - *other* set.

**See also **subtract(), operator-=(), operator|(), and operator&().

### QSet<T> & QSet::operator-= ( const QSet<T> & *other* )

Same as subtract(*other*).

**See also **operator-(), operator|=(), and operator&=().

### QSet<T> & QSet::operator-= ( const T & *value* )

Removes the occurrence of item *value* from the set, if it is found, and returns a reference to the set. If the *value* is not contained the set, nothing is removed.

### QSet<T> & QSet::operator<< ( const T & *value* )

Inserts a new item *value* and returns a reference to the set. If *value* already exists in the set, the set is left unchanged.

### QSet<T> & QSet::operator= ( const QSet<T> & *other* )

Assigns the *other* set to this set and returns a reference to this set.

### bool QSet::operator== ( const QSet<T> & *other* ) const

Returns true if the *other* set is equal to this set; otherwise returns false.

Two sets are considered equal if they contain the same elements.

This function requires the value type to implement `operator==()`.

### QSet<T> QSet::operator| ( const QSet<T> & *other* ) const

Returns a new QSet that is the union of this set and the *other* set.

**See also **unite(), operator|=(), operator&(), and operator-().

### QSet<T> & QSet::operator|= ( const QSet<T> & *other* )

Same as unite(*other*).

**See also **operator|(), operator&=(), and operator-=().

### QSet<T> & QSet::operator|= ( const T & *value* )

Inserts a new item *value* and returns a reference to the set. If *value* already exists in the set, the set is left unchanged.

## Related Non-Members

### QDataStream & operator<< ( QDataStream & *out*, const QSet<T> & *set* )

Writes the *set* to stream *out*.

This function requires the value type to implement `operator<<()`.

**See also **Format of the QDataStream operators.

### QDataStream & operator>> ( QDataStream & *in*, QSet<T> & *set* )

Reads a set from stream *in* into *set*.

This function requires the value type to implement `operator>>()`.

**See also **Format of the QDataStream operators.

© 2013 Digia Plc and/or its subsidiaries. Documentation contributions included herein are the copyrights of their respective owners.

The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.

Documentation sources may be obtained from www.qt-project.org.

Digia, Qt and their respective logos are trademarks of Digia Plc in Finland and/or other countries worldwide. All other trademarks are property of their respective owners. Privacy Policy