[#BloombergLP-bdld-DatumMapOwningKeysBuilder]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bdld.adoc[bdld]::DatumMapOwningKeysBuilder
:relfileprefix: ../../
:mrdocs:

This `class` provides a mechanism to build a `Datum` object having a map (owning keys) value in an exception‐safe manner.

== Synopsis

Declared in `<bdld_datummapowningkeysbuilder.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class DatumMapOwningKeysBuilder;
----

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/SizeType.adoc[`SizeType`] 
| `SizeType` is an alias for a signed value, representing the capacity, _keys‐capacity_, size or _keys‐size_ of a datum‐key‐owning map.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/allocator_type.adoc[`allocator_type`] 
| Allocator type used by this builder.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/2constructor-04.adoc[`DatumMapOwningKeysBuilder`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/2destructor.adoc[`~DatumMapOwningKeysBuilder`] [.small]#[destructor]#
| Destroy this object. If this object is holding a datum‐key‐owning map that has not been adopted, then the datum‐key‐owning map is disposed after destroying each of its elements.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/allocator.adoc[`allocator`] 
| Return `get_allocator().mechanism()`.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/append.adoc[`append`] 
| Append the specified array `entries` having the specified `size` to the `Datum` map (owning keys) being build by this object. The behavior is undefined unless and `0 != entries && 0 != size` and each element in `entries` that needs dynamic memory, is allocated with the same allocator that was used to construct this object. The behavior is undefined if `commit` or `sortAndCommit` has already been called on this object.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/capacity.adoc[`capacity`] 
| Return the capacity of the held `Datum` map (owning keys). The behavior is undefined if `commit` or `sortAndCommit` has already been called on this object. Note that similar to the capacity of a `vector`, the returned capacity has no bearing on the value of the `Datum` being constructed, but does indicate at which point additional memory will be required to grow the `Datum` map being built.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/commit.adoc[`commit`] 
| Return a `Datum` map (owning keys) value holding the elements supplied to `pushBack` or `append`. The caller is responsible for releasing the resources of the returned `Datum` object. Calling this method indicates that the caller is finished building the `Datum` map (owning keys) and no further values shall be appended. The behavior is undefined if any method of this object, other than its destructor, is called after `commit` invocation.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/get_allocator.adoc[`get_allocator`] 
| Return the allocator used by this object to supply memory. Note that if no allocator was supplied at construction the default allocator in effect at construction is used.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/keysCapacity.adoc[`keysCapacity`] 
| Return the keys‐capacity of the held `Datum` map (owning keys). The behavior is undefined if `commit` or `sortAndCommit` has already been called on this object. Note that similar to the capacity of a `vector`, the returned capacity has no bearing on the value of the `Datum` being constructed, but does indicate at which point additional memory will be required to grow the `Datum` map being built.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/pushBack.adoc[`pushBack`] 
| Append the entry with the specified `key` and the specified `value` to the `Datum` map being build by this object. The behavior is undefined if `value` needs dynamic memory and was allocated using a different allocator than the one used to construct this object. The behavior is also undefined if `commit` or `sortAndCommit` has already been called on this object.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/setSorted.adoc[`setSorted`] 
| Mark the Datum map (owning keys) being built by this object as sorted if the specified `value` is `true` and mark it unsorted otherwise. This function does not sort the map entries, or mark them to be sorted later; the function should be used to indicate if the entries are being appended in sorted order. The behavior is undefined if `commit` or `sortAndCommit` has already been called on this object. The behavior is also undefined if the map being constructed is marked sorted, but the entries are not appended in sorted order. Note also that the map being constructed is marked unsorted by default.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/size.adoc[`size`] 
| Return the size of the held `Datum` map (owning keys). The behavior is undefined if `commit` or `sortAndCommit` has already been called on this object.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/sortAndCommit.adoc[`sortAndCommit`] 
| Return a `Datum` map (owning keys) value holding the elements supplied to `pushBack` or `append` sorted by their keys. The caller is responsible for releasing the resources of the returned `Datum` object. Calling this method indicates that the caller is finished building the `Datum` map (owning keys) and no further values shall be appended. The behavior is undefined if any method of this object, other than its destructor, is called after `sortAndCommit` invocation.
| xref:BloombergLP/bdld/DatumMapOwningKeysBuilder/2conversion.adoc[`operator BloombergLP::bslmf::NestedTraitDeclaration<DatumMapOwningKeysBuilder, UsesBslmaAllocator>`] 
| `DatumMapOwningKeysBuilder` is allocator‐aware.
|===



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