1//===- StringMap.h - String Hash table map interface ------------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8///
9/// \file
10/// This file defines the StringMap class.
11///
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_ADT_STRINGMAP_H
15#define LLVM_ADT_STRINGMAP_H
16
17#include "llvm/ADT/StringMapEntry.h"
18#include "llvm/ADT/iterator.h"
19#include "llvm/Support/AllocatorBase.h"
20#include "llvm/Support/DJB.h"
21#include "llvm/Support/PointerLikeTypeTraits.h"
22#include <initializer_list>
23#include <iterator>
24
25namespace llvm {
26
27template <typename ValueTy> class StringMapConstIterator;
28template <typename ValueTy> class StringMapIterator;
29template <typename ValueTy> class StringMapKeyIterator;
30
31/// StringMapImpl - This is the base class of StringMap that is shared among
32/// all of its instantiations.
33class StringMapImpl {
34protected:
35 // Array of NumBuckets pointers to entries, null pointers are holes.
36 // TheTable[NumBuckets] contains a sentinel value for easy iteration. Followed
37 // by an array of the actual hash values as unsigned integers.
38 StringMapEntryBase **TheTable = nullptr;
39 unsigned NumBuckets = 0;
40 unsigned NumItems = 0;
41 unsigned NumTombstones = 0;
42 unsigned ItemSize;
43
44protected:
45 explicit StringMapImpl(unsigned itemSize) : ItemSize(itemSize) {}
46 StringMapImpl(StringMapImpl &&RHS)
47 : TheTable(RHS.TheTable), NumBuckets(RHS.NumBuckets),
48 NumItems(RHS.NumItems), NumTombstones(RHS.NumTombstones),
49 ItemSize(RHS.ItemSize) {
50 RHS.TheTable = nullptr;
51 RHS.NumBuckets = 0;
52 RHS.NumItems = 0;
53 RHS.NumTombstones = 0;
54 }
55
56 StringMapImpl(unsigned InitSize, unsigned ItemSize);
57 unsigned RehashTable(unsigned BucketNo = 0);
58
59 /// LookupBucketFor - Look up the bucket that the specified string should end
60 /// up in. If it already exists as a key in the map, the Item pointer for the
61 /// specified bucket will be non-null. Otherwise, it will be null. In either
62 /// case, the FullHashValue field of the bucket will be set to the hash value
63 /// of the string.
64 unsigned LookupBucketFor(StringRef Key) {
65 return LookupBucketFor(Key, FullHashValue: hash(Key));
66 }
67
68 /// Overload that explicitly takes precomputed hash(Key).
69 unsigned LookupBucketFor(StringRef Key, uint32_t FullHashValue);
70
71 /// FindKey - Look up the bucket that contains the specified key. If it exists
72 /// in the map, return the bucket number of the key. Otherwise return -1.
73 /// This does not modify the map.
74 int FindKey(StringRef Key) const { return FindKey(Key, FullHashValue: hash(Key)); }
75
76 /// Overload that explicitly takes precomputed hash(Key).
77 int FindKey(StringRef Key, uint32_t FullHashValue) const;
78
79 /// RemoveKey - Remove the specified StringMapEntry from the table, but do not
80 /// delete it. This aborts if the value isn't in the table.
81 void RemoveKey(StringMapEntryBase *V);
82
83 /// RemoveKey - Remove the StringMapEntry for the specified key from the
84 /// table, returning it. If the key is not in the table, this returns null.
85 StringMapEntryBase *RemoveKey(StringRef Key);
86
87 /// Allocate the table with the specified number of buckets and otherwise
88 /// setup the map as empty.
89 void init(unsigned Size);
90
91public:
92 static constexpr uintptr_t TombstoneIntVal =
93 static_cast<uintptr_t>(-1)
94 << PointerLikeTypeTraits<StringMapEntryBase *>::NumLowBitsAvailable;
95
96 static StringMapEntryBase *getTombstoneVal() {
97 return reinterpret_cast<StringMapEntryBase *>(TombstoneIntVal);
98 }
99
100 unsigned getNumBuckets() const { return NumBuckets; }
101 unsigned getNumItems() const { return NumItems; }
102
103 bool empty() const { return NumItems == 0; }
104 unsigned size() const { return NumItems; }
105
106 /// Returns the hash value that will be used for the given string.
107 /// This allows precomputing the value and passing it explicitly
108 /// to some of the functions.
109 /// The implementation of this function is not guaranteed to be stable
110 /// and may change.
111 static uint32_t hash(StringRef Key);
112
113 void swap(StringMapImpl &Other) {
114 std::swap(a&: TheTable, b&: Other.TheTable);
115 std::swap(a&: NumBuckets, b&: Other.NumBuckets);
116 std::swap(a&: NumItems, b&: Other.NumItems);
117 std::swap(a&: NumTombstones, b&: Other.NumTombstones);
118 }
119};
120
121/// StringMap - This is an unconventional map that is specialized for handling
122/// keys that are "strings", which are basically ranges of bytes. This does some
123/// funky memory allocation and hashing things to make it extremely efficient,
124/// storing the string data *after* the value in the map.
125template <typename ValueTy, typename AllocatorTy = MallocAllocator>
126class LLVM_ALLOCATORHOLDER_EMPTYBASE StringMap
127 : public StringMapImpl,
128 private detail::AllocatorHolder<AllocatorTy> {
129 using AllocTy = detail::AllocatorHolder<AllocatorTy>;
130
131public:
132 using MapEntryTy = StringMapEntry<ValueTy>;
133
134 StringMap() : StringMapImpl(static_cast<unsigned>(sizeof(MapEntryTy))) {}
135
136 explicit StringMap(unsigned InitialSize)
137 : StringMapImpl(InitialSize, static_cast<unsigned>(sizeof(MapEntryTy))) {}
138
139 explicit StringMap(AllocatorTy A)
140 : StringMapImpl(static_cast<unsigned>(sizeof(MapEntryTy))), AllocTy(A) {}
141
142 StringMap(unsigned InitialSize, AllocatorTy A)
143 : StringMapImpl(InitialSize, static_cast<unsigned>(sizeof(MapEntryTy))),
144 AllocTy(A) {}
145
146 StringMap(std::initializer_list<std::pair<StringRef, ValueTy>> List)
147 : StringMapImpl(List.size(), static_cast<unsigned>(sizeof(MapEntryTy))) {
148 insert(List);
149 }
150
151 StringMap(StringMap &&RHS)
152 : StringMapImpl(std::move(RHS)), AllocTy(std::move(RHS.getAllocator())) {}
153
154 StringMap(const StringMap &RHS)
155 : StringMapImpl(static_cast<unsigned>(sizeof(MapEntryTy))),
156 AllocTy(RHS.getAllocator()) {
157 if (RHS.empty())
158 return;
159
160 // Allocate TheTable of the same size as RHS's TheTable, and set the
161 // sentinel appropriately (and NumBuckets).
162 init(Size: RHS.NumBuckets);
163 unsigned *HashTable = (unsigned *)(TheTable + NumBuckets + 1),
164 *RHSHashTable = (unsigned *)(RHS.TheTable + NumBuckets + 1);
165
166 NumItems = RHS.NumItems;
167 NumTombstones = RHS.NumTombstones;
168 for (unsigned I = 0, E = NumBuckets; I != E; ++I) {
169 StringMapEntryBase *Bucket = RHS.TheTable[I];
170 if (!Bucket || Bucket == getTombstoneVal()) {
171 TheTable[I] = Bucket;
172 continue;
173 }
174
175 TheTable[I] = MapEntryTy::create(
176 static_cast<MapEntryTy *>(Bucket)->getKey(), getAllocator(),
177 static_cast<MapEntryTy *>(Bucket)->getValue());
178 HashTable[I] = RHSHashTable[I];
179 }
180
181 // Note that here we've copied everything from the RHS into this object,
182 // tombstones included. We could, instead, have re-probed for each key to
183 // instantiate this new object without any tombstone buckets. The
184 // assumption here is that items are rarely deleted from most StringMaps,
185 // and so tombstones are rare, so the cost of re-probing for all inputs is
186 // not worthwhile.
187 }
188
189 StringMap &operator=(StringMap RHS) {
190 StringMapImpl::swap(Other&: RHS);
191 std::swap(getAllocator(), RHS.getAllocator());
192 return *this;
193 }
194
195 ~StringMap() {
196 // Delete all the elements in the map, but don't reset the elements
197 // to default values. This is a copy of clear(), but avoids unnecessary
198 // work not required in the destructor.
199 if (!empty()) {
200 for (unsigned I = 0, E = NumBuckets; I != E; ++I) {
201 StringMapEntryBase *Bucket = TheTable[I];
202 if (Bucket && Bucket != getTombstoneVal()) {
203 static_cast<MapEntryTy *>(Bucket)->Destroy(getAllocator());
204 }
205 }
206 }
207 free(TheTable);
208 }
209
210 using AllocTy::getAllocator;
211
212 using key_type = const char *;
213 using mapped_type = ValueTy;
214 using value_type = StringMapEntry<ValueTy>;
215 using size_type = size_t;
216
217 using const_iterator = StringMapConstIterator<ValueTy>;
218 using iterator = StringMapIterator<ValueTy>;
219
220 iterator begin() { return iterator(TheTable, NumBuckets == 0); }
221 iterator end() { return iterator(TheTable + NumBuckets, true); }
222 const_iterator begin() const {
223 return const_iterator(TheTable, NumBuckets == 0);
224 }
225 const_iterator end() const {
226 return const_iterator(TheTable + NumBuckets, true);
227 }
228
229 iterator_range<StringMapKeyIterator<ValueTy>> keys() const {
230 return make_range(StringMapKeyIterator<ValueTy>(begin()),
231 StringMapKeyIterator<ValueTy>(end()));
232 }
233
234 iterator find(StringRef Key) { return find(Key, hash(Key)); }
235
236 iterator find(StringRef Key, uint32_t FullHashValue) {
237 int Bucket = FindKey(Key, FullHashValue);
238 if (Bucket == -1)
239 return end();
240 return iterator(TheTable + Bucket, true);
241 }
242
243 const_iterator find(StringRef Key) const { return find(Key, hash(Key)); }
244
245 const_iterator find(StringRef Key, uint32_t FullHashValue) const {
246 int Bucket = FindKey(Key, FullHashValue);
247 if (Bucket == -1)
248 return end();
249 return const_iterator(TheTable + Bucket, true);
250 }
251
252 /// lookup - Return the entry for the specified key, or a default
253 /// constructed value if no such entry exists.
254 ValueTy lookup(StringRef Key) const {
255 const_iterator Iter = find(Key);
256 if (Iter != end())
257 return Iter->second;
258 return ValueTy();
259 }
260
261 /// at - Return the entry for the specified key, or abort if no such
262 /// entry exists.
263 const ValueTy &at(StringRef Val) const {
264 auto Iter = this->find(std::move(Val));
265 assert(Iter != this->end() && "StringMap::at failed due to a missing key");
266 return Iter->second;
267 }
268
269 /// Lookup the ValueTy for the \p Key, or create a default constructed value
270 /// if the key is not in the map.
271 ValueTy &operator[](StringRef Key) { return try_emplace(Key).first->second; }
272
273 /// contains - Return true if the element is in the map, false otherwise.
274 bool contains(StringRef Key) const { return find(Key) != end(); }
275
276 /// count - Return 1 if the element is in the map, 0 otherwise.
277 size_type count(StringRef Key) const { return contains(Key) ? 1 : 0; }
278
279 template <typename InputTy>
280 size_type count(const StringMapEntry<InputTy> &MapEntry) const {
281 return count(MapEntry.getKey());
282 }
283
284 /// equal - check whether both of the containers are equal.
285 bool operator==(const StringMap &RHS) const {
286 if (size() != RHS.size())
287 return false;
288
289 for (const auto &KeyValue : *this) {
290 auto FindInRHS = RHS.find(KeyValue.getKey());
291
292 if (FindInRHS == RHS.end())
293 return false;
294
295 if (!(KeyValue.getValue() == FindInRHS->getValue()))
296 return false;
297 }
298
299 return true;
300 }
301
302 bool operator!=(const StringMap &RHS) const { return !(*this == RHS); }
303
304 /// insert - Insert the specified key/value pair into the map. If the key
305 /// already exists in the map, return false and ignore the request, otherwise
306 /// insert it and return true.
307 bool insert(MapEntryTy *KeyValue) {
308 unsigned BucketNo = LookupBucketFor(KeyValue->getKey());
309 StringMapEntryBase *&Bucket = TheTable[BucketNo];
310 if (Bucket && Bucket != getTombstoneVal())
311 return false; // Already exists in map.
312
313 if (Bucket == getTombstoneVal())
314 --NumTombstones;
315 Bucket = KeyValue;
316 ++NumItems;
317 assert(NumItems + NumTombstones <= NumBuckets);
318
319 RehashTable();
320 return true;
321 }
322
323 /// insert - Inserts the specified key/value pair into the map if the key
324 /// isn't already in the map. The bool component of the returned pair is true
325 /// if and only if the insertion takes place, and the iterator component of
326 /// the pair points to the element with key equivalent to the key of the pair.
327 std::pair<iterator, bool> insert(std::pair<StringRef, ValueTy> KV) {
328 return try_emplace_with_hash(KV.first, hash(Key: KV.first),
329 std::move(KV.second));
330 }
331
332 std::pair<iterator, bool> insert(std::pair<StringRef, ValueTy> KV,
333 uint32_t FullHashValue) {
334 return try_emplace_with_hash(KV.first, FullHashValue, std::move(KV.second));
335 }
336
337 /// Inserts elements from range [first, last). If multiple elements in the
338 /// range have keys that compare equivalent, it is unspecified which element
339 /// is inserted .
340 template <typename InputIt> void insert(InputIt First, InputIt Last) {
341 for (InputIt It = First; It != Last; ++It)
342 insert(*It);
343 }
344
345 /// Inserts elements from initializer list ilist. If multiple elements in
346 /// the range have keys that compare equivalent, it is unspecified which
347 /// element is inserted
348 void insert(std::initializer_list<std::pair<StringRef, ValueTy>> List) {
349 insert(List.begin(), List.end());
350 }
351
352 /// Inserts an element or assigns to the current element if the key already
353 /// exists. The return type is the same as try_emplace.
354 template <typename V>
355 std::pair<iterator, bool> insert_or_assign(StringRef Key, V &&Val) {
356 auto Ret = try_emplace(Key, std::forward<V>(Val));
357 if (!Ret.second)
358 Ret.first->second = std::forward<V>(Val);
359 return Ret;
360 }
361
362 /// Emplace a new element for the specified key into the map if the key isn't
363 /// already in the map. The bool component of the returned pair is true
364 /// if and only if the insertion takes place, and the iterator component of
365 /// the pair points to the element with key equivalent to the key of the pair.
366 template <typename... ArgsTy>
367 std::pair<iterator, bool> try_emplace(StringRef Key, ArgsTy &&...Args) {
368 return try_emplace_with_hash(Key, hash(Key), std::forward<ArgsTy>(Args)...);
369 }
370
371 template <typename... ArgsTy>
372 std::pair<iterator, bool> try_emplace_with_hash(StringRef Key,
373 uint32_t FullHashValue,
374 ArgsTy &&...Args) {
375 unsigned BucketNo = LookupBucketFor(Key, FullHashValue);
376 StringMapEntryBase *&Bucket = TheTable[BucketNo];
377 if (Bucket && Bucket != getTombstoneVal())
378 return std::make_pair(iterator(TheTable + BucketNo, false),
379 false); // Already exists in map.
380
381 if (Bucket == getTombstoneVal())
382 --NumTombstones;
383 Bucket =
384 MapEntryTy::create(Key, getAllocator(), std::forward<ArgsTy>(Args)...);
385 ++NumItems;
386 assert(NumItems + NumTombstones <= NumBuckets);
387
388 BucketNo = RehashTable(BucketNo);
389 return std::make_pair(iterator(TheTable + BucketNo, false), true);
390 }
391
392 // clear - Empties out the StringMap
393 void clear() {
394 if (empty())
395 return;
396
397 // Zap all values, resetting the keys back to non-present (not tombstone),
398 // which is safe because we're removing all elements.
399 for (unsigned I = 0, E = NumBuckets; I != E; ++I) {
400 StringMapEntryBase *&Bucket = TheTable[I];
401 if (Bucket && Bucket != getTombstoneVal()) {
402 static_cast<MapEntryTy *>(Bucket)->Destroy(getAllocator());
403 }
404 Bucket = nullptr;
405 }
406
407 NumItems = 0;
408 NumTombstones = 0;
409 }
410
411 /// remove - Remove the specified key/value pair from the map, but do not
412 /// erase it. This aborts if the key is not in the map.
413 void remove(MapEntryTy *KeyValue) { RemoveKey(KeyValue); }
414
415 void erase(iterator I) {
416 MapEntryTy &V = *I;
417 remove(KeyValue: &V);
418 V.Destroy(getAllocator());
419 }
420
421 bool erase(StringRef Key) {
422 iterator I = find(Key);
423 if (I == end())
424 return false;
425 erase(I);
426 return true;
427 }
428};
429
430template <typename DerivedTy, typename ValueTy>
431class StringMapIterBase
432 : public iterator_facade_base<DerivedTy, std::forward_iterator_tag,
433 ValueTy> {
434protected:
435 StringMapEntryBase **Ptr = nullptr;
436
437public:
438 StringMapIterBase() = default;
439
440 explicit StringMapIterBase(StringMapEntryBase **Bucket,
441 bool NoAdvance = false)
442 : Ptr(Bucket) {
443 if (!NoAdvance)
444 AdvancePastEmptyBuckets();
445 }
446
447 DerivedTy &operator=(const DerivedTy &Other) {
448 Ptr = Other.Ptr;
449 return static_cast<DerivedTy &>(*this);
450 }
451
452 friend bool operator==(const DerivedTy &LHS, const DerivedTy &RHS) {
453 return LHS.Ptr == RHS.Ptr;
454 }
455
456 DerivedTy &operator++() { // Preincrement
457 ++Ptr;
458 AdvancePastEmptyBuckets();
459 return static_cast<DerivedTy &>(*this);
460 }
461
462 DerivedTy operator++(int) { // Post-increment
463 DerivedTy Tmp(Ptr);
464 ++*this;
465 return Tmp;
466 }
467
468private:
469 void AdvancePastEmptyBuckets() {
470 while (*Ptr == nullptr || *Ptr == StringMapImpl::getTombstoneVal())
471 ++Ptr;
472 }
473};
474
475template <typename ValueTy>
476class StringMapConstIterator
477 : public StringMapIterBase<StringMapConstIterator<ValueTy>,
478 const StringMapEntry<ValueTy>> {
479 using base = StringMapIterBase<StringMapConstIterator<ValueTy>,
480 const StringMapEntry<ValueTy>>;
481
482public:
483 StringMapConstIterator() = default;
484 explicit StringMapConstIterator(StringMapEntryBase **Bucket,
485 bool NoAdvance = false)
486 : base(Bucket, NoAdvance) {}
487
488 const StringMapEntry<ValueTy> &operator*() const {
489 return *static_cast<const StringMapEntry<ValueTy> *>(*this->Ptr);
490 }
491};
492
493template <typename ValueTy>
494class StringMapIterator : public StringMapIterBase<StringMapIterator<ValueTy>,
495 StringMapEntry<ValueTy>> {
496 using base =
497 StringMapIterBase<StringMapIterator<ValueTy>, StringMapEntry<ValueTy>>;
498
499public:
500 StringMapIterator() = default;
501 explicit StringMapIterator(StringMapEntryBase **Bucket,
502 bool NoAdvance = false)
503 : base(Bucket, NoAdvance) {}
504
505 StringMapEntry<ValueTy> &operator*() const {
506 return *static_cast<StringMapEntry<ValueTy> *>(*this->Ptr);
507 }
508
509 operator StringMapConstIterator<ValueTy>() const {
510 return StringMapConstIterator<ValueTy>(this->Ptr, true);
511 }
512};
513
514template <typename ValueTy>
515class StringMapKeyIterator
516 : public iterator_adaptor_base<StringMapKeyIterator<ValueTy>,
517 StringMapConstIterator<ValueTy>,
518 std::forward_iterator_tag, StringRef> {
519 using base = iterator_adaptor_base<StringMapKeyIterator<ValueTy>,
520 StringMapConstIterator<ValueTy>,
521 std::forward_iterator_tag, StringRef>;
522
523public:
524 StringMapKeyIterator() = default;
525 explicit StringMapKeyIterator(StringMapConstIterator<ValueTy> Iter)
526 : base(std::move(Iter)) {}
527
528 StringRef operator*() const { return this->wrapped()->getKey(); }
529};
530
531} // end namespace llvm
532
533#endif // LLVM_ADT_STRINGMAP_H
534

source code of llvm/include/llvm/ADT/StringMap.h