Component ball_userfields [Package ball]

Provide a container of user supplied field values. More...

Namespaces
namespace	ball

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Basic Use of ball::UserFields

Purpose:

Provide a container of user supplied field values.

Classes:

ball::UserFields

a container of user supplied field values

See also:

Component ball_userfieldvalue

Description:

This component provides a value-semantic container-type, ball::UserFields, that represents a (randomly accessible) sequence of ball::UserFieldValue objects. Each user field value contained in the sequence functions as a discriminated union of the types described by ball::UserFieldType::Enum (integer, double, string, etc). Values can be added to the sequence using the append* manipulators, and can be manipulated and accessed using operator[]. Additionally, ball::UserFields exposes a random-access iterator providing non-modifiable access to the sequence through the begin and end methods.

Usage:

This section illustrates intended use of this component.

Example 1: Basic Use of ball::UserFields:

In the following example we demonstrate populating a ball::UserFields object with a sequence of field values.

First, we define the signature for a callback, populateUserFields. Most often ball::UserFields objects are populated by a callback, such as the one described by the ball::LoggerManagerConfiguration UserFieldsPopulatorCallback.

  void populateLoggingFields(ball::UserFields *fields)
      // Populate the specified 'fields' with the username and current task
      // identifier.  The behavior is undefined unless 'fields' is empty.
  {

Next, we assert the precondition that fields is empty:

    BSLS_ASSERT(0 == fields->length());

Now, we populate the fields object with the username and current task identifier (for the purpose of illustration, these are simply constants):

    static const char               *TEST_USER = "testUser";
    static const bsls::Types::Int64  TEST_TASK = 4315;

    fields->appendString(TEST_USER);
    fields->appendInt64(TEST_TASK);

Finally, for the purposes of illustration, we verify that fields has been set correctly:

    assert(2              == fields->length());
    assert(Type::e_STRING == fields->value(0).type());
    assert(TEST_USER      == fields->value(0).theString());
    assert(Type::e_INT64  == fields->value(1).type());
    assert(TEST_TASK      == fields->value(1).theInt64());
  }