ball_attributecontainerlist

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Thread Safety
  • Usage
    • Example 1: Basic Usage of ball::AttributeContainerList

Purpose

Provide a list of attribute container addresses.

Classes

• ball::AttributeContainerList: a list of container addresses
• ball::AttributeContainerListIterator: an iterator over a container list

See also

ball_attribute, ball_attributecontainer

Description

This component defines a class ball::AttributeContainerList that provides a linked list of ball::AttributeContainer object addresses. Addresses can be prepended (to the front of the list) using the pushFront() method. The pushFront() method returns an iterator that can be used later to efficiently remove the added element. The ball::AttributeContainerList also provides a hasValue() operation, that returns true if any of the attribute containers in the list contain the supplied attribute, and false otherwise. The ball::AttributeContainerList maintains a store of free list-nodes to minimize the amount of memory allocation required if addresses are frequently added and removed from the container. This component also defines a class ball::AttributeContainerListIterator (as well as the alias ball::AttributeContainerList::iterator) that provides an STL-style iterator over the addresses in a ball::AttributeContainer.

This component participates in the implementation of "Rule-Based Logging". For more information on how to use that feature, please see the package level documentation and usage examples for "Rule-Based Logging".

Thread Safety

ball::AttributeContainerList is const thread-safe, meaning that accessors may be invoked concurrently from different threads, but it is not safe to access or modify a ball::AttributeContainerList in one thread while another thread modifies the same object.

Usage

This section illustrates intended use of this component.

Example 1: Basic Usage of ball::AttributeContainerList

In the following example we demonstrate how to create a ball::AttributeContainerList object, how to add and remove elements from the list, and how to walk the list of attribute container addresses.

We start by creating three attribute sets that we will use to populate our attribute container list. Note that this example uses the AttributeSet implementation of the ball::AttributeContainer protocol defined in the ball_attributecontainer component documentation.

AttributeSet s1, s2, s3;
s1.insert(ball::AttributeValue("Set1", 1));
s2.insert(ball::AttributeValue("Set2", 2));
s3.insert(ball::AttributeValue("Set3", 3));

We now create a ball::AttributeContainerList and add the three attribute container addresses to the list:

ball::AttributeContainerList exampleList;
ball::AttributeContainerList::iterator s1Iter = exampleList.pushFront(&s1);
ball::AttributeContainerList::iterator s2Iter = exampleList.pushFront(&s2);
ball::AttributeContainerList::iterator s3Iter = exampleList.pushFront(&s3);

We can use the hasValue() operation to test which attribute value are contained within the list of containers:

assert(true == exampleList.hasValue("Set1", 1));
assert(true == exampleList.hasValue("Set2", 2));
assert(true == exampleList.hasValue("Set3", 3));
 
assert(false == exampleList.hasValue("Set1", 2));
assert(false == exampleList.hasValue("Set2", 1));
assert(false == exampleList.hasValue("Set4", 1));

We can use the iterators to efficiently remove elements from the list:

exampleList.remove(s3Iter);

Finally, we can use either the stream operator or the print() method to print the attributes within an attribute container list:

bsl::cout << exampleList << bsl::endl;

The resulting output will be the following:

[  [  [ Set2 = 2 ]  ]  [  [ Set1 = 1 ]  ] ]

Note that the output shows the values in s2 (i.e., ("Set2", 2)) and then the values in s1 (i.e., ("Set1", 1)).