ball_userfields

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

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.

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

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());
}