Class attribute_value_set

boost::log::attribute_value_set — A set of attribute values.

Synopsis

// In header: <boost/log/attributes/attribute_value_set.hpp>


class attribute_value_set {
public:
  // types
  typedef attribute_name                           key_type;         // Key type. 
  typedef attribute_value                          mapped_type;      // Mapped attribute type. 
  typedef std::pair< const key_type, mapped_type > value_type;       // Value type. 
  typedef value_type &                             reference;        // Reference type. 
  typedef value_type const  &                      const_reference;  // Const reference type. 
  typedef value_type *                             pointer;          // Pointer type. 
  typedef value_type const  *                      const_pointer;    // Const pointer type. 
  typedef std::size_t                              size_type;        // Size type. 
  typedef std::ptrdiff_t                           difference_type;  // Pointer difference type. 
  typedef implementation_defined                   const_iterator; 

  // construct/copy/destruct
  explicit attribute_value_set(size_type = 8);
  attribute_value_set(attribute_value_set &&) noexcept;
  attribute_value_set(attribute_set const &, attribute_set const &, 
                      attribute_set const &, size_type = 8);
  attribute_value_set(attribute_value_set const &, attribute_set const &, 
                      attribute_set const &, size_type = 8);
  attribute_value_set(attribute_value_set &&, attribute_set const &, 
                      attribute_set const &, size_type = 8);
  attribute_value_set(attribute_value_set const &);
  attribute_value_set & operator=(attribute_value_set) noexcept;
  ~attribute_value_set();

  // public member functions
  void swap(attribute_value_set &) noexcept;
  const_iterator begin() const;
  const_iterator end() const;
  size_type size() const;
  bool empty() const;
  const_iterator find(key_type) const;
  mapped_type operator[](key_type) const;
  template<typename DescriptorT, template< typename > class ActorT> 
    result_of::extract< typename expressions::attribute_keyword< DescriptorT, ActorT >::value_type, DescriptorT >::type 
    operator[](expressions::attribute_keyword< DescriptorT, ActorT > const &) const;
  size_type count(key_type) const;
  void freeze();
  std::pair< const_iterator, bool > insert(key_type, mapped_type const &);
  std::pair< const_iterator, bool > insert(const_reference);
  template<typename FwdIteratorT> void insert(FwdIteratorT, FwdIteratorT);
  template<typename FwdIteratorT, typename OutputIteratorT> 
    void insert(FwdIteratorT, FwdIteratorT, OutputIteratorT);
};

Description

The set of attribute values is an associative container with attribute name as a key and a pointer to attribute value object as a mapped type. This is a collection of elements with unique keys, that is, there can be only one attribute value with a given name in the set. With respect to read-only capabilities, the set interface is close to std::unordered_map.

The set is designed to be only capable of adding elements to it. Once added, the attribute value cannot be removed from the set.

An instance of attribute value set can be constructed from three attribute sets. The constructor attempts to accommodate values of all attributes from the sets. The situation when a same-named attribute is found in more than one attribute set is possible. This problem is solved on construction of the value set: the three attribute sets have different priorities when it comes to solving conflicts.

From the library perspective the three source attribute sets are global, thread-specific and source-specific attributes, with the latter having the highest priority. This feature allows to override attributes of wider scopes with the more specific ones.

For sake of performance, the attribute values are not immediately acquired from attribute sets at construction. Instead, on-demand acquisition is performed either on iterator dereferencing or on call to the freeze method. Once acquired, the attribute value stays within the set until its destruction. This nuance does not affect other set properties, such as size or lookup ability. The logging core automatically freezes the set at the right point, so users should not be bothered unless they manually create attribute value sets.

	Note
	The attribute sets that were used for the value set construction must not be modified or destroyed until the value set is frozen. Otherwise the behavior is undefined.

`attribute_value_set` public types

typedef implementation_defined const_iterator;

Constant iterator type with bidirectional capabilities.

`attribute_value_set` public construct/copy/destruct

```
explicit attribute_value_set(size_type reserve_count = 8);
```
Default constructor

The constructor creates an empty set which can be filled later by subsequent calls of insert method. Optionally, the amount of storage reserved for elements to be inserted may be passed to the constructor. The constructed set is frozen.

Parameters:

reserve_count

Number of elements to reserve space for.

attribute_value_set(attribute_value_set && that) noexcept;

Move constructor

attribute_value_set(attribute_set const & source_attrs, 
                    attribute_set const & thread_attrs, 
                    attribute_set const & global_attrs, 
                    size_type reserve_count = 8);

The constructor adopts three attribute sets into the value set. The source_attrs attributes have the greatest preference when a same-named attribute is found in several sets, global_attrs has the least. The constructed set is not frozen.

Parameters:

`global_attrs`	A set of global attributes.
`reserve_count`	Amount of elements to reserve space for, in addition to the elements in the three attribute sets provided.
`source_attrs`	A set of source-specific attributes.
`thread_attrs`	A set of thread-specific attributes.

attribute_value_set(attribute_value_set const & source_attrs, 
                    attribute_set const & thread_attrs, 
                    attribute_set const & global_attrs, 
                    size_type reserve_count = 8);

Parameters:

`global_attrs`	A set of global attributes.
`reserve_count`	Amount of elements to reserve space for, in addition to the elements in the three attribute sets provided.
`source_attrs`	A set of source-specific attributes.
`thread_attrs`	A set of thread-specific attributes.

Requires:

The source_attrs set is frozen.

attribute_value_set(attribute_value_set && source_attrs, 
                    attribute_set const & thread_attrs, 
                    attribute_set const & global_attrs, 
                    size_type reserve_count = 8);

Parameters:

`global_attrs`	A set of global attributes.
`reserve_count`	Amount of elements to reserve space for, in addition to the elements in the three attribute sets provided.
`source_attrs`	A set of source-specific attributes.
`thread_attrs`	A set of thread-specific attributes.

Requires:

The source_attrs set is frozen.

```
attribute_value_set(attribute_value_set const & that);
```
Copy constructor.

Requires:

The original set is frozen.

Postconditions:

The constructed set is frozen, std::equal(begin(), end(), that.begin()) == true

attribute_value_set & operator=(attribute_value_set that) noexcept;

Assignment operator

```
~attribute_value_set();
```
Destructor. Releases all referenced attribute values.

`attribute_value_set` public member functions

void swap(attribute_value_set & that) noexcept;

Swaps two sets

Throws: Nothing.

```
const_iterator begin() const;
```
Returns:

Iterator to the first element of the set.
```
const_iterator end() const;
```
Returns:

Iterator to the after-the-last element of the set.
```
size_type size() const;
```
Returns:

Number of elements in the set.
```
bool empty() const;
```
Returns:

true if there are no elements in the container, false otherwise.
```
const_iterator find(key_type key) const;
```
The method finds the attribute value by name.

Parameters:

key

Attribute name.

Returns:

Iterator to the found element or end() if the attribute with such name is not found.
```
mapped_type operator[](key_type key) const;
```
Alternative lookup syntax.

Parameters:

key

Attribute name.

Returns:

A pointer to the attribute value if it is found with key, default-constructed mapped value otherwise.

template<typename DescriptorT, template< typename > class ActorT> 
  result_of::extract< typename expressions::attribute_keyword< DescriptorT, ActorT >::value_type, DescriptorT >::type 
  operator[](expressions::attribute_keyword< DescriptorT, ActorT > const & keyword) const;

Alternative lookup syntax.

Parameters:

keyword

Attribute keyword.

Returns:

A value_ref with extracted attribute value if it is found, empty value_ref otherwise.

```
size_type count(key_type key) const;
```
The method counts the number of the attribute value occurrences in the set. Since there can be only one attribute value with a particular key, the method always return 0 or 1.

Parameters:

key

Attribute name.

Returns:

The number of times the attribute value is found in the container.
```
void freeze();
```
The method acquires values of all adopted attributes.

Postconditions:

The set is frozen.

std::pair< const_iterator, bool > 
insert(key_type key, mapped_type const & mapped);

Inserts an element into the set. The complexity of the operation is amortized constant.

Parameters:

`key`	The attribute name.
`mapped`	The attribute value.

Requires:

The set is frozen.

Returns:

An iterator to the inserted element and true if insertion succeeded. Otherwise, if the set already contains a same-named attribute value, iterator to the existing element and false.

std::pair< const_iterator, bool > insert(const_reference value);

Inserts an element into the set. The complexity of the operation is amortized constant.

Parameters:

value

The attribute name and value.

Requires:

The set is frozen.

Returns:

An iterator to the inserted element and true if insertion succeeded. Otherwise, if the set already contains a same-named attribute value, iterator to the existing element and false.

template<typename FwdIteratorT> 
  void insert(FwdIteratorT begin, FwdIteratorT end);

Mass insertion method. The complexity of the operation is linear to the number of elements inserted.

Parameters:

`begin`	A forward iterator that points to the first element to be inserted.
`end`	A forward iterator that points to the after-the-last element to be inserted.

Requires:

The set is frozen.

template<typename FwdIteratorT, typename OutputIteratorT> 
  void insert(FwdIteratorT begin, FwdIteratorT end, OutputIteratorT out);

Mass insertion method with ability to acquire iterators to the inserted elements. The complexity of the operation is linear to the number of elements inserted times the complexity of filling the out iterator.

Parameters:

`begin`	A forward iterator that points to the first element to be inserted.
`end`	A forward iterator that points to the after-the-last element to be inserted.
`out`	An output iterator that receives results of insertion of the elements.

Requires:

The set is frozen.

Requires:	The original set is frozen.
Postconditions:	The constructed set is frozen, `std::equal(begin(), end(), that.begin()) == true`

Boost C++ Libraries