Component bdld_datumintmapbuilder [Package bdld]

Provide a utility to build a Datum object holding an int-map. More...

Namespaces
namespace	bdld

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Syntax

Purpose:

Provide a utility to build a Datum object holding an int-map.

Classes:

bdld::DatumIntMapBuilder

utility to build Datum objects holding int-maps

See also:

Component bdld_datum

Description:

This component defines a mechanism, bdld::DatumIntMapBuilder, used to populate a Datum int-map value in an exception-safe manner. In addition to providing exception safety, a DatumIntMapBuilder is particularly useful when the size of the int-map to be constructed is not known in advance. The user can append elements to the datum int-map as needed, and when there are no more elements to append the user calls commit or sortAndCommit and ownership of the populated Datum object is transferred to the caller. After calling commit or sortAndCommit, no additional elements can be appended to the Datum int-map value. Note that sortAndCommit method will sort the populated int-map (by keys) and tag the resulting Datum int-map value as sorted. Also note that the user can insert elements in a (ascending) sorted order and tag the int-map as sorted. The behavior is undefined if unsorted int-map is tagged sorted.

Usage:

This section illustrates intended use of this component.

Example 1: Basic Syntax:

Suppose we need a data map for some UX data. The keys of the map are 32-bit integers; and the values in that map can be different types. The following code illustrates how to use bdld::DatumIntMapBuilder to create such map easily.

First, we need data to fill our int-map:

  bslma::TestAllocator ta("test", veryVeryVerbose);

  DatumIntMapEntry formData[] = {
      DatumIntMapEntry(1, Datum::createStringRef("Bart", &ta)),
      DatumIntMapEntry(2, Datum::createStringRef("Simpson", &ta)),
      DatumIntMapEntry(3, Datum::createStringRef("male", &ta)),
      DatumIntMapEntry(4, Datum::createInteger(10))
  };

  const size_t DATA_SIZE  = sizeof(formData) / sizeof(DatumIntMapEntry);

Next, we create an object of DatumIntMapBuilder class with initial capacity sufficient for storing all our data:

  DatumIntMapBuilder builder(DATA_SIZE, &ta);

Then, we load our builder with these data:

  for (size_t i = 0; i < DATA_SIZE; ++i) {
      builder.pushBack(formData[i].key(), formData[i].value());
  }

Next, we adopt the int-map, held by our builder, by newly created Datum object:

  Datum form = builder.commit();

Now, we can check that all data have been correctly added to the int-map at the required order:

  assert(true == form.isIntMap());
  assert(DATA_SIZE == form.theIntMap().size());

  assert(1           == form.theIntMap()[0].key());
  assert(true        == form.theIntMap()[0].value().isString());
  assert("Bart"      == form.theIntMap()[0].value().theString());

  assert(2           == form.theIntMap()[1].key());
  assert(true        == form.theIntMap()[1].value().isString());
  assert("Simpson"   == form.theIntMap()[1].value().theString());

  assert(3           == form.theIntMap()[2].key());
  assert(true        == form.theIntMap()[2].value().isString());
  assert("male"      == form.theIntMap()[2].value().theString());

  assert(4           == form.theIntMap()[3].key());
  assert(true        == form.theIntMap()[3].value().isInteger());
  assert(10          == form.theIntMap()[3].value().theInteger());

Finally, we destroy the Datum object to release all allocated memory correctly:

  Datum::destroy(form, &ta);
  assert(0 == ta.numBytesInUse());