QHash Class

Documentation des fonctions membres

[noexcept default] QHash::QHash()

Crée un hachage vide.

Voir aussi clear().

QHash::QHash(std::initializer_list<std::pair<Key, T>> list)

Crée un hachage contenant une copie de chacun des éléments de la liste d'initialisation list.

template <typename InputIterator> QHash::QHash(InputIterator begin, InputIterator end)

Construit un hachage à partir d'une copie de chacun des éléments de la plage d'itérateurs [begin, end). Soit les éléments parcourus par la plage doivent être des objets comportant les membres de données first et second (comme std::pair), convertibles respectivement en Key et en T; soit les itérateurs doivent disposer des fonctions membres key() et value(), renvoyant respectivement une clé convertible en Key et une valeur convertible en T.

[noexcept] QHash::QHash(const QHash<Key, T> &other)

Crée une copie de other.

Cette opération s'effectue en temps constant, car QHash est implicitement partagé. Cela rend très rapide le retour d’un QHash depuis une fonction. Si une instance partagée est modifiée, elle sera copiée (copie à l’écriture), ce qui prend un temps linéaire.

Voir également operator=().

[noexcept] QHash::QHash(QHash<Key, T> &&other)

Crée une instance de QHash par « move », de sorte qu'elle pointe vers le même objet que celui vers lequel pointait other.

QHash::~QHash()

Supprime le hachage. Les références aux valeurs contenues dans ce hachage ainsi que tous les itérateurs associés à celui-ci deviennent invalides.

Renvoie un objet « range » qui permet de parcourir ce hachage sous forme de paires clé/valeur. Par exemple, cet objet « range » peut être utilisé dans une boucle « for » basée sur une plage, en combinaison avec une déclaration de liaison structurée :

QHash<QString, int> hash;
hash.insert("January", 1);
hash.insert("February", 2);
// ...
hash.insert("December", 12);

for (auto [key, value] : hash.asKeyValueRange()) {
    cout << qPrintable(key) << ": " << value << endl;
    --value; // convert to JS month indexing
}

Notez que la clé et la valeur obtenues de cette manière sont toutes deux des références à celles contenues dans le hachage. Plus précisément, la modification de la valeur entraînera la modification du hachage lui-même.

Ces fonctions ont été introduites dans Qt 6.4.

Voir également QKeyValueIterator.

QHash<Key, T>::iterator QHash::begin()

Renvoie un itérateur de type STL pointant vers le premier élément du hachage.

Voir également constBegin() et end().

[noexcept] QHash<Key, T>::const_iterator QHash::begin() const

[noexcept] qsizetype QHash::capacity() const

Renvoie le nombre de compartiments dans la table de hachage interne de QHash.

Cette fonction a pour seul objectif de permettre un réglage fin de l'utilisation de la mémoire par la fonction « QHash ». En général, vous n'aurez que très rarement besoin d'appeler cette fonction. Si vous souhaitez connaître le nombre d'éléments contenus dans le hachage, appelez la fonction « size »().

Voir également reserve() et squeeze().

[noexcept] QHash<Key, T>::const_iterator QHash::cbegin() const

Renvoie un itérateur de type STL constant pointant vers le premier élément du hachage.

Voir aussi begin() et cend().

[noexcept] QHash<Key, T>::const_iterator QHash::cend() const

Renvoie un itérateur constant de type STL pointant vers l'élément imaginaire situé après le dernier élément du hachage.

Voir également cbegin() et end().

[noexcept(...)] void QHash::clear()

Supprime tous les éléments du hachage et libère toute la mémoire qu'il occupe.

Voir également ` remove()`.

[noexcept] QHash<Key, T>::const_iterator QHash::constBegin() const

Renvoie un itérateur const de type STL pointant vers le premier élément du hachage.

Voir également begin() et constEnd().

[noexcept] QHash<Key, T>::const_iterator QHash::constEnd() const

Renvoie un itérateur de type STL constant pointant vers l'élément imaginaire situé après le dernier élément du hachage.

Voir également constBegin() et end().

[noexcept] QHash<Key, T>::const_iterator QHash::constFind(const Key &key) const

Renvoie un itérateur pointant vers l'élément de l'key dans le hachage.

Si le hachage ne contient aucun élément portant l'key, la fonction renvoie constEnd().

Voir aussi find().

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::constKeyValueBegin() const

Renvoie un itérateur de type const, conforme à la norme STL, pointant vers la première entrée du hachage.

Voir également ` keyValueBegin()`.

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::constKeyValueEnd() const

Renvoie un itérateur de type STL « const » pointant vers l'entrée imaginaire située après la dernière entrée du hachage.

Voir aussi ` constKeyValueBegin()`.

[noexcept] bool QHash::contains(const Key &key) const

Renvoie « true » si le hachage contient un élément dont la valeur est « key » ; sinon, renvoie « false ».

Voir aussi count().

[noexcept] qsizetype QHash::count(const Key &key) const

Renvoie le nombre d'éléments associés à l'key.

Voir aussi contains().

[noexcept] qsizetype QHash::count() const

Identique à ` size()`.

Insère un nouvel élément dans le conteneur. Ce nouvel élément est construit sur place à l'aide de ` args ` comme arguments de construction. Si l'élément existe déjà dans le conteneur, il est remplacé.

Renvoie un itérateur pointant vers le nouvel élément.

[noexcept] bool QHash::empty() const

Cette fonction est fournie à des fins de compatibilité avec la STL. Elle est équivalente à ` isEmpty()`, qui renvoie `true` si le hachage est vide ; dans le cas contraire, elle renvoie ` false`.

[noexcept] QHash<Key, T>::iterator QHash::end()

Renvoie un itérateur de type STL pointant vers l'élément imaginaire situé après le dernier élément du hachage.

Voir également begin() et constEnd().

[noexcept] QHash<Key, T>::const_iterator QHash::end() const

QHash<Key, T>::iterator QHash::erase(QHash<Key, T>::const_iterator pos)

Supprime de l'pos la paire (clé, valeur) associée à l' de l' , puis renvoie un itérateur vers l'élément suivant de l' .

Cette fonction ne provoque jamais de réorganisation de la structure de données interne d'QHash. Cela signifie qu'elle peut être appelée en toute sécurité pendant une itération et qu'elle n'affectera pas l'ordre des éléments dans le hachage. Par exemple :

QHash<QObject *, int> objectHash;
//...
QHash<QObject *, int>::iterator i = objectHash.find(obj);
while (i != objectHash.end() && i.key() == obj) {
    if (i.value() == 0) {
        i = objectHash.erase(i);
    } else {
        ++i;
    }
}

Voir également remove(), take() et find().

QHash<Key, T>::iterator QHash::find(const Key &key)

Renvoie un itérateur pointant vers l'élément de l'key dans le hachage.

Si le hachage ne contient aucun élément portant l'key, la fonction renvoie ` end()`.

Si le hachage contient plusieurs éléments portant l'key, cette fonction renvoie un itérateur pointant vers la valeur insérée le plus récemment. Les autres valeurs sont accessibles en incrémentant l'itérateur. Voici, par exemple, un extrait de code qui parcourt tous les éléments portant la même clé :

QHash<QString, int> hash;
//...
QHash<QString, int>::const_iterator i = hash.find("HDR");
while (i != hash.end() && i.key() == "HDR") {
    cout << i.value() << endl;
    ++i;
}

Voir également value() et values().

[noexcept] QHash<Key, T>::const_iterator QHash::find(const Key &key) const

void QHash::insert(const QHash<Key, T> &other)

Insère tous les éléments du hachage other dans ce hachage.

Si une clé est commune aux deux hachages, sa valeur sera remplacée par celle stockée dans ` other`.

QHash<Key, T>::iterator QHash::insert(const Key &key, const T &value)

Insère un nouvel élément avec l'key et la valeur value.

S'il existe déjà un élément avec l'key, la valeur de cet élément est remplacée par value.

L'insertion d'une paire clé/valeur avec une clé existante remplace la valeur existante.

Renvoie un itérateur pointant vers l’élément nouveau ou mis à jour.

Ces fonctions ont été introduites dans Qt 6.11.

Tente d'insérer un élément avec les valeurs key et value. Si un élément avec la valeur key existe déjà, sa valeur est écrasée par value.

Renvoie une instance de ` TryEmplaceResult`, une structure contenant une ` iterator ` vers l’élément, ainsi qu’un booléen, ` inserted`, indiquant si l’élément a été nouvellement créé (`true`) ou s’il existait déjà (`false`).

Ces fonctions ont été introduites dans Qt 6.9.

Voir également insert(), tryEmplace() et tryInsert().

Tente d'insérer un élément avec les valeurs key et value. Si un élément avec key existe déjà, sa valeur est écrasée par value.

Renvoie un couple composé d'un itérateur pointant vers l'élément et d'un booléen indiquant si l'élément a été nouvellement créé (true) ou s'il existait déjà (false).

Ces fonctions sont fournies à des fins de compatibilité avec la bibliothèque standard.

Ces fonctions ont été introduites dans Qt 6.9.

Voir également insert(), tryEmplace(), tryInsert() et insertOrAssign().

Tente d’insérer un élément avec les valeurs key et value. Si un élément avec la valeur key existe déjà, sa valeur est écrasée par value.

Renvoie une paire composée d’un itérateur pointant vers l’élément et d’un booléen indiquant si l’élément a été nouvellement créé (true) ou s’il existait déjà (false).

hint est ignoré.

Ces fonctions sont fournies à des fins de compatibilité avec la bibliothèque standard.

Ces fonctions ont été introduites dans Qt 6.9.

Voir également insert(), tryEmplace() et insertOrAssign().

[noexcept] bool QHash::isEmpty() const

Renvoie « true » si le hachage ne contient aucun élément ; sinon, renvoie « false ».

Voir aussi size().

Renvoie la première clé associée à value. Si le hachage ne contient aucun élément associé à value, renvoie defaultKey, ou une clé construite par défaut si ce paramètre n'a pas été fourni.

Cette fonction peut être lente (temps linéaire), car la structure de données interne de ` QHash` est optimisée pour une recherche rapide par clé, et non par valeur.

[noexcept] QHash<Key, T>::key_iterator QHash::keyBegin() const

Renvoie un itérateur de type STL constant pointant vers la première clé du hachage.

Voir aussi ` keyEnd()`.

[noexcept] QHash<Key, T>::key_iterator QHash::keyEnd() const

Renvoie un itérateur constant de type STL pointant vers l'élément imaginaire situé après la dernière clé du hachage.

Voir aussi ` keyBegin()`.

QHash<Key, T>::key_value_iterator QHash::keyValueBegin()

Renvoie un itérateur de type STL pointant vers la première entrée du hachage.

Voir aussi ` keyValueEnd()`.

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::keyValueBegin() const

Renvoie un itérateur de type STL constant pointant vers la première entrée du hachage.

Voir également ` keyValueEnd()`.

QHash<Key, T>::key_value_iterator QHash::keyValueEnd()

Renvoie un itérateur de type STL pointant vers l'entrée imaginaire située après la dernière entrée du hachage.

Voir aussi keyValueBegin().

[noexcept] QHash<Key, T>::const_key_value_iterator QHash::keyValueEnd() const

Renvoie un itérateur constant de type STL pointant vers l'entrée imaginaire située après la dernière entrée du hachage.

Voir aussi ` keyValueBegin()`.

QList<Key> QHash::keys() const

Renvoie une liste contenant toutes les clés du hachage, dans un ordre aléatoire.

L'ordre est garanti d'être le même que celui utilisé par values().

Cette fonction crée une nouvelle liste, en temps linéaire. La consommation de temps et de mémoire que cela implique peut être évitée en itérant de ` keyBegin()` à ` keyEnd()`.

Voir également values() et key().

QList<Key> QHash::keys(const T &value) const

Renvoie une liste contenant toutes les clés associées à la valeur value, dans un ordre aléatoire.

Cette fonction peut être lente (temps linéaire), car la structure de données interne de ` QHash` est optimisée pour une recherche rapide par clé, et non par valeur.

[noexcept] float QHash::load_factor() const

Renvoie le facteur de charge actuel de la table de hachage interne de l’ QHash. Cette fonction est équivalente à capacity()/size(). L’implémentation utilisée visera à maintenir le facteur de charge entre 0,25 et 0,5. Cela permet d’éviter un nombre trop élevé de collisions dans la table de hachage, qui pourraient nuire aux performances.

Même avec un faible facteur de charge, l'implémentation de la table de hachage n'entraîne qu'une très faible surconsommation de mémoire.

Cette méthode est exclusivement destinée à des fins de diagnostic et vous ne devriez que très rarement avoir besoin de l'appeler vous-même.

Voir également reserve() et squeeze().

bool QHash::remove(const Key &key)

Supprime de l'espace de noms l'élément dont la clé est « key ». Renvoie « true » si la clé existe dans l'espace de noms et que l'élément a bien été supprimé, et « false » dans le cas contraire.

Voir également ` clear()` et ` take()`.

[since 6.1] template <typename Predicate> qsizetype QHash::removeIf(Predicate pred)

Supprime du hachage tous les éléments pour lesquels le prédicat pred renvoie « vrai ».

La fonction prend en charge les prédicats qui acceptent soit un argument de type QHash<Key, T>::iterator, soit un argument de type std::pair<const Key &, T &>.

Renvoie le nombre d'éléments supprimés, le cas échéant.

Cette fonction a été introduite dans Qt 6.1.

Voir également clear() et take().

void QHash::reserve(qsizetype size)

Garantit que la table de hachage interne de ` QHash` dispose de suffisamment d'espace pour stocker au moins ` size ` éléments sans avoir à agrandir la table de hachage.

Cela implique que la table de hachage contiendra au moins 2 * size compartiments afin de garantir de bonnes performances

Cette fonction est utile pour le code qui doit construire un hachage de grande taille et qui souhaite éviter des réallocations répétées. Par exemple :

QHash<QString, int> hash;
hash.reserve(20000);
for (int i = 0; i < 20000; ++i)
    hash.insert(keys[i], values[i]);

Idéalement, size devrait correspondre au nombre maximal d’éléments attendus dans le hachage. QHash choisira alors le plus petit nombre possible de compartiments permettant de stocker size éléments dans la table sans avoir à agrandir la table de hachage interne. Si size est sous-estimé, le pire qui puisse arriver est que l’ QHash soit légèrement plus lente.

En général, vous n’aurez que très rarement besoin d’appeler cette fonction. La table de hachage interne de QHash s’agrandit automatiquement pour offrir de bonnes performances sans gaspiller trop de mémoire.

Voir également squeeze() et capacity().

[noexcept] qsizetype QHash::size() const

Renvoie le nombre d'éléments contenus dans le hachage.

Voir également isEmpty() et count().

void QHash::squeeze()

Réduit la taille de la table de hachage interne de l'QHash afin d'économiser de la mémoire.

Le seul but de cette fonction est de permettre un réglage fin de l’utilisation de la mémoire par QHash. En général, vous n’aurez que très rarement besoin d’appeler cette fonction.

Voir également ` reserve()` et ` capacity()`.

[noexcept] void QHash::swap(QHash<Key, T> &other)

Permute cette valeur de hachage avec celle de other. Cette opération est très rapide et ne rencontre jamais d'échec.

T QHash::take(const Key &key)

Supprime de l'key l'élément portant l' et renvoie la valeur qui lui est associée.

Si l'élément n'existe pas dans le hachage, la fonction renvoie simplement une valeur construite par défaut.

Si vous n'utilisez pas la valeur renvoyée, la fonction ` remove()` est plus efficace.

Voir aussi remove().

Insère un nouvel élément avec l'key et une valeur construite à partir de args. Si un élément avec l'key existe déjà, aucune insertion n'a lieu.

Renvoie une instance de ` TryEmplaceResult`, une structure contenant une ` iterator ` vers l’élément nouvellement créé, ou vers l’élément préexistant qui a empêché l’insertion, ainsi qu’un booléen, ` inserted`, indiquant si l’insertion a eu lieu.

Par exemple, cela peut être utilisé pour éviter de comparer l’ancienne et la nouvelle taille ou d’effectuer des recherches doubles. Là où vous auriez auparavant écrit un code tel que :

QHash<int, MyType> hash;
// [...]
int myKey = getKey();
qsizetype oldSize = hash.size();
MyType &elem = hash[myKey];
if (oldSize != hash.size()) // Size changed: new element!
    initialize(elem);
// [use elem...]

Vous pouvez désormais écrire :

QHash<int, MyType> hash;
// [...]
int myKey = getKey();
auto result = hash.tryEmplace(myKey);
if (result.inserted) // New element!
    initialize(*result.iterator);
// [use result.iterator...]

Ces fonctions ont été introduites dans Qt 6.9.

Voir également emplace(), tryInsert() et insertOrAssign().

Insère un nouvel élément avec l'key et la valeur value. Si un élément portant l'key existe déjà, aucune insertion n'a lieu.

Renvoie une instance de ` TryEmplaceResult`, une structure contenant un ` iterator ` vers l'élément nouvellement créé, ou vers l'élément préexistant qui a empêché l'insertion, ainsi qu'un booléen, ` inserted`, indiquant si l'insertion a eu lieu.

Ces fonctions ont été introduites dans Qt 6.9.

Voir également insert(), tryEmplace() et insertOrAssign().

Insère un nouvel élément dont l'key et la valeur sont dérivés de args. Si un élément dont l'key existe déjà, aucune insertion n'a lieu.

Renvoie un couple composé d'un itérateur vers l'élément inséré (ou vers l'élément qui a empêché l'insertion) et d'un booléen indiquant si l'insertion a eu lieu.

Ces fonctions sont fournies à des fins de compatibilité avec la bibliothèque standard.

Ces fonctions ont été introduites dans Qt 6.9.

Voir également emplace(), tryEmplace(), tryInsert() et insertOrAssign().

Insère un nouvel élément dont l'key est spécifié et dont la valeur est construite à partir de args. Si un élément dont l'key est déjà présent, aucune insertion n'a lieu.

Renvoie l'itérateur de l'élément inséré, ou celui de l'élément qui a empêché l'insertion.

hint est ignoré.

Ces fonctions sont fournies à des fins de compatibilité avec la bibliothèque standard.

Ces fonctions ont été introduites dans Qt 6.9.

Voir également emplace(), tryEmplace(), tryInsert() et insertOrAssign().

Renvoie la valeur associée à l'key.

Si le hachage ne contient aucun élément correspondant à l'key, la fonction renvoie defaultValue, ou une valeur construite par défaut si ce paramètre n'a pas été fourni.

QList<T> QHash::values() const

Renvoie une liste contenant toutes les valeurs du hachage, dans un ordre aléatoire.

L'ordre est garanti d'être identique à celui utilisé par la fonction keys().

Cette fonction crée une nouvelle liste, en temps linéaire. La consommation de temps et de mémoire que cela implique peut être évitée en itérant de ` keyValueBegin()` à ` keyValueEnd()`.

Voir également keys() et value().

[noexcept] QHash<Key, T> &QHash::operator=(QHash<Key, T> &&other)

Cette opération attribue l'other à cette instance QHash.

[noexcept] QHash<Key, T> &QHash::operator=(const QHash<Key, T> &other)

Attribue la valeur « other » à ce hachage et renvoie une référence à ce hachage.

T &QHash::operator[](const Key &key)

Renvoie la valeur associée à l'key sous forme de référence modifiable.

Si le hachage ne contient aucun élément portant l'key, la fonction insère dans le hachage une valeur construite par défaut portant l'key, puis renvoie une référence à celle-ci.

Voir également insert() et value().

[noexcept] const T QHash::operator[](const Key &key) const

Identique à ` value()`.