[#BloombergLP-bdlcc-StripedUnorderedMap]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdlcc.adoc[bdlcc]::StripedUnorderedMap
:relfileprefix: ../../
:mrdocs:

This class template defines a fully thread&hyphen;safe container that provides a mapping from keys (of template parameter type `KEY`) to their associated mapped values (of template parameter type `VALUE`)&period;

== Synopsis

Declared in `&lt;bdlcc&lowbar;stripedunorderedmap&period;h&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template&lt;
    class KEY,
    class VALUE,
    class HASH = xref:bsl/hash-06.adoc[bsl::hash&lt;KEY&gt;],
    class EQUAL = xref:bsl/equal_to-0d.adoc[bsl::equal&lowbar;to&lt;KEY&gt;]&gt;
class StripedUnorderedMap;
----

== Description

The buckets of this hash map are guarded by `numStripes` reader&hyphen;writer locks, a value specified on construction&period; Partitioning the buckets among several locks allows greater overall concurrency than a `bsl&colon;&colon;unordered&lowbar;map` object guarded by a single lock&period;

The interface is inspired by, but not identical to that of `bsl&colon;&colon;unordered&lowbar;map`&period; Notably absent are iterators, which are of limited practicality in the typical use case because they are readily invalidated when the map population is open to modification by multiple threads&period;

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/StripedUnorderedMap/EraseIfValuePredicate.adoc[`EraseIfValuePredicate`] 
| An alias to a function meeting the following contract&colon; &grave; &sol;&sol;&sol; Return `true` if the specified `value` is to be removed from &sol;&sol;&sol; the container, and `false` otherwise&period; Note that this &sol;&sol;&sol; functor can _not_ change the values associated with `value`&period; bool eraseIfValuePredicate(const VALUE&amp; value)&semi; &grave;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/KVType.adoc[`KVType`] 
| Value type of a bulk insert entry&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/ReadOnlyVisitorFunction.adoc[`ReadOnlyVisitorFunction`] 
| An alias to a function meeting the following contract&colon; &grave; &sol;&sol;&sol; Visit the specified `value` attribute associated with the &sol;&sol;&sol; specified `key`&period; Return `true` if this function may be &sol;&sol;&sol; called on additional elements, and `false` otherwise (i&period;e&period;, &sol;&sol;&sol; if no other elements should be visited)&period; Note that this &sol;&sol;&sol; functor can _not_ change the value associated with `key` &sol;&sol;&sol; and `value`&period; bool visitorFunction(const VALUE&amp; value, const KEY&amp; key)&semi; &grave;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/VisitorFunction.adoc[`VisitorFunction`] 
| An alias to a function meeting the following contract&colon; &grave; &sol;&sol;&sol; Visit the specified `value` attribute associated with the &sol;&sol;&sol; specified `key`&period; Return `true` if this function may be &sol;&sol;&sol; called on additional elements, and `false` otherwise (i&period;e&period;, &sol;&sol;&sol; if no other elements should be visited)&period; Note that this &sol;&sol;&sol; functor can change the value associated with `key`&period; bool visitorFunction(VALUE &ast;value, const KEY&amp; key)&semi; &grave;
|===


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/StripedUnorderedMap/_04enum.adoc[`Unnamed enum`] 
| Default sizing constants for this map&period;
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/StripedUnorderedMap/2constructor-03.adoc[`StripedUnorderedMap`]         [.small]#[constructor]#
| Create an empty `StripedUnorderedMap` object, a fully thread&hyphen;safe hash map where access is partitioned into &quot;stripes&quot; (a group of buckets protected a reader&hyphen;writer mutex)&period; Optionally specify `numInitialBuckets` and `numStripes` which define the minimum number of buckets and the (fixed) number of stripes in this map&period; Optionally specify a `basicAllocator` used to supply memory&period; If `basicAllocator` is 0, the currently installed default allocator is used&period; The hash map has rehash enabled&period; Note that the number of stripes will not change after construction, but the number of buckets may (unless rehashing is disabled via `disableRehash`)&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/allocator.adoc[`allocator`] 
| Return the allocator used by this hash map to supply memory&period; Note that if no allocator was supplied at construction the default allocator installed at that time is used&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/bucketCount.adoc[`bucketCount`] 
| Return the number of buckets in the array of buckets maintained by this hash map&period; Note that unless rehash is disabled, the value returned may be obsolete by the time it is received&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/bucketIndex.adoc[`bucketIndex`] 
| Return the index of the bucket, in the array of buckets maintained by this hash map, where elements having the specified `key` are inserted&period; Note that unless rehash is disabled, the value returned may be obsolete at the time it is returned&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/bucketSize.adoc[`bucketSize`] 
| Return the number of elements contained in the bucket at the specified `index` in the array of buckets maintained by this hash map&period; The behavior is undefined unless `0 &lt;&equals; index &lt; bucketCount()`&period; Note that unless rehash is disabled the value returned may be obsolete by the time it is returned&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/clear.adoc[`clear`] 
| Remove all elements from this hash map&period; If rehash is in progress, block until it completes&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/disableRehash.adoc[`disableRehash`] 
| Prevent future rehash until `enableRehash` is called&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/empty.adoc[`empty`] 
| Return `true` if this hash map contains no elements, and `false` otherwise&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/enableRehash.adoc[`enableRehash`] 
| Allow rehash&period; If conditions warrant, rehash will be started by the _next_ method call that observes the load factor is exceeded (see &lcub;Concurrent Rehash&rcub;)&period; Note that calling `maxLoadFactor(maxLoadFactor())` (i&period;e&period;, setting the maximum load factor to its current value) will trigger a rehash if needed but otherwise does not change the hash map&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/equalFunction.adoc[`equalFunction`] 
| Return (a copy of) the key&hyphen;equality functor used by this hash map&period; The returned function will return `true` if two `KEY` objects have the same value, and `false` otherwise&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/erase.adoc[`erase`] 
| Erase from this hash map the element having the specified `key`&period; Return 1 on success and 0 if `key` does not exist&period; Note that the returned value equals the number of elements removed&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/eraseBulk.adoc[`eraseBulk`] 
| Erase from this hash map elements in this hash map having any of the values in the keys contained between the specified `first` (inclusive) and `last` (exclusive) random&hyphen;access iterators&period; The iterators provide read access to a sequence of `KEY` objects&period; All erasures are done by the calling thread and the order of erasure is not specified&period; Return the number of elements removed&period; The behavior is undefined unless `first &lt;&equals; last`&period; Note that the map may not have an element for every value in `keys`&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/eraseIf.adoc[`eraseIf`] 
| Remove from this hash map the element, if any, having the specified `key`, where specified `predicate` holds true&period; Return the number of elements erased&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/getValue.adoc[`getValue`] 
| Load, into the specified `&ast;value`, the value attribute of the element in this hash map having the specified `key`&period; Return 1 on success and 0 if `key` does not exist in this hash map&period; Note that the return value equals the number of values returned&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/hashFunction.adoc[`hashFunction`] 
| Return (a copy of) the unary hash functor used by this hash map&period; The return function will generate a hash value (of type `std&colon;&colon;size&lowbar;t`) for a `KEY` object&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/insert-08.adoc[`insert`] 
| `insert` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedMap/insertBulk.adoc[`insertBulk`] 
| Insert into this hash map elements having the key&hyphen;value pairs obtained between the specified `first` (inclusive) and `last` (exclusive) random&hyphen;access iterators&period; The iterators provide read access to a sequence of `bsl&colon;&colon;pair&lt;KEY, VALUE&gt;` objects&period; If an element having one of the keys already exists in this hash map, set the value attribute to the corresponding value from `data`&period; All insertions are done by the calling thread and the order of insertion is not specified&period; Return the number of elements inserted&period; The behavior is undefined unless `first &lt;&equals; last`&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/isRehashEnabled.adoc[`isRehashEnabled`] 
| Return `true` if rehash is enabled, or `false` otherwise&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/loadFactor.adoc[`loadFactor`] 
| Return the current quotient of the size of this hash map and the number of buckets&period; Note that the load factor is a measure of container &quot;fullness&quot;&semi; that is, a high load factor typically implies many collisions (many elements landing in the same bucket) and that decreases performance&period; See &lcub;Rehash Control&rcub;&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/maxLoadFactor.adoc[`maxLoadFactor`] 
| Return the maximum load factor allowed for this hash map&period; If an insert operation would cause the load factor to exceed the `maxLoadFactor()` and rehashing is enabled, then that insert increases the number of buckets and rehashes the elements of the container into that larger set of buckets&period; See &lcub;Rehash Control&rcub;&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/numStripes.adoc[`numStripes`] 
| Return the number of stripes in the hash&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/rehash.adoc[`rehash`] 
| Recreate this hash map to one having at least the specified `numBuckets`&period; This operation is a no&hyphen;op if _any_ of the following are true&colon; 1) rehash is disabled&semi; 2) `numBuckets` less or equals the current number of buckets&period; See &lcub;Rehash&rcub;&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/setComputedValue.adoc[`setComputedValue`] 
| Invoke the specified `visitor` on the value associated with the specified `key`&period; The `visitor` will be passed the address of the value, and `key`&period; If `key` is not in the map, `value` will be default constructed&period; That is, `visitor` must be invocable with the `VisitorFunction` signature&colon; &grave; bool visitor(VALUE &ast;value, const Key&amp; key)&semi; &grave; If no element in the map has `key`, insert `(key, VALUE())` and invoke `visitor` with `value` pointing to the default constructed value&period; Return 1 if `key` was found and `visitor` returned `true`, 0 if `key` was not found, and &hyphen;1 if `key` was found and `visitor` returned `false`&period; `visitor`, when invoked, has exclusive access (i&period;e&period;, write access) to the element&period; The behavior is undefined if hash map manipulators and `getValue&ast;` methods are invoked from within `visitor`, as it may lead to a deadlock&period; Note that the return value equals the number of elements found having `key`&period; Also note that a return value of `0` implies that an element was inserted&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/setValue-0f.adoc[`setValue`] 
| `setValue` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedMap/size.adoc[`size`] 
| Return the current number of elements in this hash map&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/update.adoc[`update`] 
| Call the specified `visitor` with the element (if one exists) in this hash map having the specified `key`&period; That is&colon; &grave; bool visitor(&amp;value, key)&semi; &grave; Return the number of elements updated or &hyphen;1 if `visitor` returned `false`&period; `visitor` has exclusive access (i&period;e&period;, write access) the element for during its invocation&period; The behavior is undefined if hash map manipulators and `getValue&ast;` methods are invoked from within `visitor`, as it may lead to a deadlock&period;
| xref:BloombergLP/bdlcc/StripedUnorderedMap/visit-0c.adoc[`visit`] 
| `visit` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedMap/visitReadOnly-04.adoc[`visitReadOnly`] 
| `visitReadOnly` overloads
|===



[.small]#Created with https://www.mrdocs.com[MrDocs]#
