Class template basic_attribute_values

Class template basic_attribute_values_view

boost::log::basic_attribute_values_view — A view of attribute values.

Synopsis

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

template<typename CharT> 
class basic_attribute_values_view : private std::allocator< char > {
public:
  // types
  typedef CharT                                    char_type;           // Character type. 
  typedef std::basic_string< char_type >           string_type;         // String type. 
  typedef basic_slim_string< char_type >           key_type;            // Key type. 
  typedef shared_ptr< attribute_value >            mapped_type;         // Mapped attribute type. 
  typedef basic_attribute_set< char_type >         attribute_set_type;  // Corresponding attribute set type. 
  typedef std::pair< const key_type, mapped_type > value_type;          // Value type. 
  typedef std::allocator< value_type >             allocator_type;      // Allocator type. 
  typedef allocator_type::reference                reference;           // Reference type. 
  typedef allocator_type::const_reference          const_reference;     // Const reference type. 
  typedef allocator_type::pointer                  pointer;             // Pointer type. 
  typedef allocator_type::const_pointer            const_pointer;       // Const pointer type. 
  typedef allocator_type::size_type                size_type;           // Size type. 
  typedef allocator_type::difference_type          difference_type;     // Pointer difference type. 
  typedef implementation_defined const_iterator;

  // construct/copy/destruct
  basic_attribute_values_view(attribute_set_type const &, 
                              attribute_set_type const &, 
                              attribute_set_type const &);
  basic_attribute_values_view(basic_attribute_values_view const &);
  basic_attribute_values_view& operator=(basic_attribute_values_view const &);
  ~basic_attribute_values_view();

  // public member functions
  void swap(basic_attribute_values_view &);
  const_iterator begin() const;
  const_iterator end() const;
  size_type size() const;
  bool empty() const;
  const_iterator find(key_type const &) const;
  const_iterator find(string_type const &) const;
  const_iterator find(const char_type *) const;
  mapped_type operator[](key_type const &) const;
  mapped_type operator[](string_type const &) const;
  mapped_type operator[](const char_type *) const;
  size_type count(key_type const &) const;
  size_type count(string_type const &) const;
  size_type count(const char_type *) const;
  void freeze();
};

Description

Attribute values view is a read-only 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 a view. With respect to read-only capabilities, attribute values view is close to std::map.

An instance of attribute values view can be constructed from three attribute sets and attempts to accommodate values all attributes from the sets. The situation when a same-named attribute is found in more than one attribute is possible. This problem is solved on construction of the view: 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.

After the view construction it cannot be modified. However, for sake of performance, the attribute values are not immediately acquired on the view construction. Instead, on-demand acquision is performed either on iterator dereferencing or on call to the freeze method. Once acquired, the attribute value stays within the view until its destruction. This nuance does not affect other view properties, such as size or lookup ability. The logging core automatically freezes the view at the right point, so users should not be bothered.

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

`basic_attribute_values_view` public types

typedef implementation_defined const_iterator;

Constant iterator type with bidirectional capabilities.

`basic_attribute_values_view` public construct/copy/destruct

```
basic_attribute_values_view(attribute_set_type const & source_attrs, 
                            attribute_set_type const & thread_attrs, 
                            attribute_set_type const & global_attrs);
```
The constructor adopts three attribute sets into the view. 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 view is not frozen.

Parameters:

global_attrs
A set of global attributes.

source_attrs
A set of source-specific attributes.

thread_attrs
A set of thread-specific attributes.
```
basic_attribute_values_view(basic_attribute_values_view const & that);
```
Copy constructor.

Requires:
The original view is frozen.

Postconditions:
The constructed view is frozen, std::equal(begin(), end(), that.begin()) == true
```
basic_attribute_values_view& 
operator=(basic_attribute_values_view const & that);
```
Assignment operator

Requires:
The original view is frozen.

Postconditions:
The resulting view is frozen, std::equal(begin(), end(), that.begin()) == true
```
~basic_attribute_values_view();
```
Destructor. Releases all referenced attribute values.

`basic_attribute_values_view` public member functions

void swap(basic_attribute_values_view & that);

Swaps two views

Throws: Nothing.

```
const_iterator begin() const;
```
Returns:
Iterator to the first element of the view.
```
const_iterator end() const;
```
Returns:
Iterator to the after-the-last element of the view.
```
size_type size() const;
```
Returns:
Number of elements in the view.
```
bool empty() const;
```
Returns:
true if there are no elements in the container, false otherwise.
```
const_iterator find(key_type const & 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.
```
const_iterator find(string_type const & 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.
```
const_iterator find(const char_type * key) const;
```
The method finds the attribute value by name.

Parameters:

key
Attribute name. Must not be NULL, must point to a zero-terminated string.

Returns:
Iterator to the found element or end() if the attribute with such name is not found.
```
mapped_type operator[](key_type const & 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.
```
mapped_type operator[](string_type const & 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.

mapped_type operator[](const char_type * key) const;

Alternative lookup syntax.

Parameters:

key

Attribute name. Must not be NULL, must point to a zero-terminated string.

Returns:

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

```
size_type count(key_type const & key) const;
```
The method counts the number of the attribute value occurrences in the view. 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.
```
size_type count(string_type const & key) const;
```
The method counts the number of the attribute value occurrences in the view. 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.
```
size_type count(const char_type * key) const;
```
The method counts the number of the attribute value occurrences in the view. Since there can be only one attribute value with a particular key, the method always return 0 or 1.

Parameters:

key
Attribute name. Must not be NULL, must point to a zero-terminated string.

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 view is frozen

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