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

This class implements the logic for a striped hash multimap with logic that supports a (unique) map as a special case.

== Synopsis

Declared in `<bdlcc_stripedunorderedcontainerimpl.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class KEY,
    class VALUE,
    class HASH = xref:bsl/hash-06.adoc[bsl::hash<KEY>],
    class EQUAL = xref:bsl/equal_to-0d.adoc[bsl::equal_to<KEY>]>
class StripedUnorderedContainerImpl;
----

== Type Aliases

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


== Enums

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/_04enum.adoc[`Unnamed enum`] 
| Default sizing constants for this container.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/2constructor-072.adoc[`StripedUnorderedContainerImpl`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/2destructor.adoc[`~StripedUnorderedContainerImpl`] [.small]#[destructor]#
| Destroy this hash map. This method is _not_ thread‐safe.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/allocator.adoc[`allocator`] 
| Return the allocator used by this hash map to supply memory. Note that if no allocator was supplied at construction the default allocator installed at that time is used.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/bucketCount.adoc[`bucketCount`] 
| Return the number of buckets in the array of buckets maintained by this hash map. Note that unless rehash is disabled, the value returned may be obsolete by the time it is received.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/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. Note that unless rehash is disabled, the value returned may be obsolete at the time it is returned.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/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. The behavior is undefined unless `0 <= index < bucketCount()`.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/canRehash.adoc[`canRehash`] 
| Return `true` if rehash is enabled and rehash is not in progress, and `false` otherwise.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/clear.adoc[`clear`] 
| Remove all elements from this striped hash map. If rehash is in progress, block until it completes.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/disableRehash.adoc[`disableRehash`] 
| Prevent rehash until the `enableRehash` method is called.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/empty.adoc[`empty`] 
| Return `true` if this hash map contains no elements, and `false` otherwise.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/enableRehash.adoc[`enableRehash`] 
| Allow rehash. If conditions warrant, rehash will be started by the _next_ method call that observes the load factor is exceeded (see {Concurrent Rehash}). Note that calling `maxLoadFactor(maxLoadFactor())` (i.e., setting the maximum load factor to its current value) will trigger a rehash if needed but otherwise does not change the hash map.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/equalFunction.adoc[`equalFunction`] 
| Return (a copy of) the key‐equality functor used by this hash map that returns `true` if two `KEY` objects have the same value, and `false` otherwise.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/eraseAll.adoc[`eraseAll`] 
| Erase from this hash map the elements having the specified `key`. Return the number of elements erased.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/eraseAllIf.adoc[`eraseAllIf`] 
| Erase from this hash map the elements having the specified `key` for which the specified `predicate` holds true. Return the number of elements erased.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/eraseBulkAll.adoc[`eraseBulkAll`] 
| 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‐access iterators. The iterators provide read access to a sequence of `KEY` objects. All erasures are done by the calling thread and the order of erasure is not specified. Return the number of elements removed. The behavior is undefined unless `first <= last`. Note that the map may not have an element for every value in `keys`.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/eraseBulkFirst.adoc[`eraseBulkFirst`] 
| 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‐access iterators. The iterators provide read access to a sequence of `KEY` objects. If there are multiple elements for any key value, erase just the first such element found. All erasures are done by the calling thread and the order of erasure is not specified. Return the number of elements removed. The behavior is undefined unless `first <= last`. Note that the map may not have an element for every value in `keys`.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/eraseFirst.adoc[`eraseFirst`] 
| Erase from this hash map the _first_ element (of possibly many) found to the specified `key`. Return the number of elements erased. Note that method is more performant than `eraseAll` when there is one element having `key`.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/eraseFirstIf.adoc[`eraseFirstIf`] 
| Erase from this hash map the _first_ element with specified `key` (of possibly many) found, for which the specified `predicate` holds true. Return the number of elements erased.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/getValue-0b.adoc[`getValue`] 
| `getValue` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/hashFunction.adoc[`hashFunction`] 
| Return (a copy of) the unary hash functor used by this hash map to generate a hash value (of type `std::size_t`) for a `KEY` object.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/insertAlways-0c.adoc[`insertAlways`] 
| `insertAlways` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/insertBulkAlways.adoc[`insertBulkAlways`] 
| Insert into this hash map elements having the key‐value pairs obtained between the specified `first` (inclusive) and `last` (exclusive) random‐access iterators. The iterators provide read access to a sequence of `bsl::pair<KEY, VALUE>` objects. All insertions are done by the calling thread and the order of insertion is not specified. The behavior is undefined unless `first <= last`.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/insertBulkUnique.adoc[`insertBulkUnique`] 
| Insert into this hash map elements having the key‐value pairs obtained between the specified `first` (inclusive) and `last` (exclusive) random‐access iterators. The iterators provide read access to a sequence of `bsl::pair<KEY, VALUE>` objects. If an element having one of the keys already exists in this hash map, set the value attribute to the corresponding value from `data`. All insertions are done by the calling thread and the order of insertion is not specified. Return the number of elements inserted. The behavior is undefined unless `first <= last`.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/insertUnique-0b.adoc[`insertUnique`] 
| `insertUnique` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/isRehashEnabled.adoc[`isRehashEnabled`] 
| Return `true` if rehash is enabled, or `false` otherwise.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/loadFactor.adoc[`loadFactor`] 
| Return the current quotient of the size of this hash map and the number of buckets. Note that the load factor is a measure of container "fullness"; that is, a high load factor typically implies many collisions (many elements landing in the same bucket) and that decreases performance.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/maxLoadFactor.adoc[`maxLoadFactor`] 
| Return the maximum load factor allowed for this hash map. 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.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/numStripes.adoc[`numStripes`] 
| Return the number of stripes in the hash.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/rehash.adoc[`rehash`] 
| Recreate this hash map to one having at least the specified `numBuckets`. This operation is a no‐op if _any_ of the following are true: 1) rehash is disabled; 2) `numBuckets` less or equals the current number of buckets. See {Rehash}.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/setComputedValueAll.adoc[`setComputedValueAll`] 
| Serially invoke the specified `visitor` passing the specified `key`, and the address of the value of each element in this hash map having `key`. If `key` is not in the map, `value` will be default constructed. That is, for each `(key, value)` found, invoke: ` bool visitor(VALUE *value, const Key& key); ` If no element in the map has `key`, insert `(key, VALUE())` and invoke `visitor` with `value` pointing to the defsult constructed value. Return the number of elements visited or the negation of that value if visitations stopped because `visitor` returned `false`. `visitor`, when invoked, has exclusive access (i.e., write access) to each element during each invocation. The behavior is undefined if hash map manipulators and `getValue*` methods are invoked from within `visitor`, as it may lead to a deadlock. Note that the `setComputedValueFirst` method is more performant than the when the hash map contains a single element for `key`. Also note that a return value of `0` implies that an element was inserted.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/setComputedValueFirst.adoc[`setComputedValueFirst`] 
| Invoke the specified `visitor` passing the specified `key`, and the address of the value attribute of the _first_ element (of possibly many elements) found in this hash map having `key`. If `key` is not in the map, `value` will be default constructed. That is, for `(key, value)`, invoke: ` bool visitor(VALUE *value, const Key& key); ` If no element in the map has `key`, insert `(key, VALUE())` and invoke `visitor` with `value` pointing to the defsult constructed value. Return 1 if `key` was found and `visitor` returned `true`, 0 if `key` was not found, and ‐1 if `key` was found and `visitor` returned `false`. `visitor`, when invoked, has exclusive access (i.e., write access) to the element. The behavior is undefined if hash map manipulators and `getValue*` methods are invoked from within `visitor`, as it may lead to a deadlock. Note that the return value equals the number of elements inserted. Also note that, when there are multiple elements having `key`, the selection of "first" is implementation specific and subject to change. Also note that this method is more performant than the `setComputedValueAll` method when the hash map contains a single element for `key`. Also note that a return value of `0` implies that an element was inserted.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/setValueAll.adoc[`setValueAll`] 
| Set the value attribute of every element in this hash map having the specified `key` to the specified `value`. If no such such element exists, insert `(key, value)`. Return the number of elements found with `key`. Note that if no elements were found, and a new value was inserted, `0` is returned.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/setValueFirst-0e.adoc[`setValueFirst`] 
| `setValueFirst` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/size.adoc[`size`] 
| Return the current number of elements in this hash.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/update.adoc[`update`] 
| Serially call the specified `visitor` on each element (if one exists) in this hash map having the specified `key` until every such element has been updated or `visitor` returns `false`. That is, for `(key, value)`, invoke: ` bool visitor(&value, key); ` Return the number of elements visited or the negation of that value if visitations stopped because `visitor` returned `false`. `visitor` has exclusive access (i.e., write access) to each element for duration of each invocation. The behavior is undefined if hash map manipulators and `getValue*` methods are invoked from within `visitor`, as it may lead to a deadlock.
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/visit-0a3.adoc[`visit`] 
| `visit` overloads
| xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl/visitReadOnly-02.adoc[`visitReadOnly`] 
| `visitReadOnly` overloads
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl_LockElement.adoc[BloombergLP::bdlcc::StripedUnorderedContainerImpl_LockElement]`
| A mutex + support info; padded to cacheline size, one per stripe
| `xref:BloombergLP/bdlcc/StripedUnorderedContainerImpl_TestUtil.adoc[BloombergLP::bdlcc::StripedUnorderedContainerImpl_TestUtil]`
| This class implements a test utility that gives the test driver access to the lock / unlock method of the Read/Write mutex. Its purpose is to allow testing that the locking actually happens as planned.
|===


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