Store a Parsed Attribute Value into a Container (Qi)

push_back_container

The template push_back_container is a type used as an attribute customization point. It is invoked by the Qi repetitive parsers (Kleene, Plus, List, and Repeat) to store a parsed attribute value into a container.

Module Headers

#include <boost/spirit/home/support/container.hpp>

Also, see Include Structure.

	Note
	This header file does not need to be included directly by any user program as it is normally included by other Spirit header files relying on its content.

Namespace

Name
`boost::spirit::traits`

Synopsis

template <typename Container, typename Attrib, typename Enable>
struct push_back_container
{
    static bool call(Container& c, Attrib const& val);
};

Template parameters

Parameter	Description	Default
`Container`	The type, `Container` needs to be tested whether it has to be treated as a container	none
`Attrib`	The type, `Attrib` is the one returned from the customization point `traits::container_value` and represents the attribute value to be stored in the container of type `Container`.	none
`Enable`	Helper template parameter usable to selectively enable or disable certain specializations of `push_back_container` utilizing SFINAE (i.e. `boost::enable_if` or `boost::disable_if`).	`void`

Notation

C

A type to be used as a container to store attribute values in.

c

A container instance of type C.

[Attrib

A type to be used as a container to store attribute values in.

attr

An attribute instance of type Attrib.

T1, T2, ...

Arbitrary types

Expression Semantics

Expression	Semantics
push_back_container<C, Attrib>::call(c, attr)	Static function that is invoked whenever an attribute value, `attr` needs to be stored into the container instance `c`. This function should return `true` on success and `false` otherwise. Returning `false` causes the corresponding parser to fail.

Expression

Semantics

push_back_container<C, Attrib>::call(c, attr)

Static function that is invoked whenever an attribute value, attr needs to be stored into the container instance c. This function should return true on success and false otherwise. Returning false causes the corresponding parser to fail.

Predefined Specializations

Spirit predefines specializations of this customization point for several types. The following table lists those types together with the types exposed and the corresponding semantics:

Template Parameters	Semantics
`C`, `Attrib`	Store the provided attribute instance `attr` into the given container `c` using the function call `c.insert(c.end(), attr)`.
`boost::optional<C>`, `Attrib`	If the provided instance of `boost::optional<>` is not initialized, invoke the appropriate initialization and afterwards apply the customization point `push_back_container<C, Attrib>`, treating the instance held by the optional (of type `C`) as the container to store the attribute in.
`boost::variant<T1, T2, ...>`, `Attrib`	If the instance of the variant currently holds a value with a type, `TN`, for which `is_container<TN>::type` evaluates to `mpl::true_`, this customization point specialization will apply `push_back_container<TN, Attrib>`, treating the instance held by the variant (of type `TN`) as the container to store the attribute in. Otherwise it will raise an assertion.
`unused_type`	Do nothing.

When to Implement

The customization point push_back_container needs to be implemented for a specific type whenever this type is to be used as an attribute in place of a STL container. It is applicable for parsers (Spirit.Qi) only. As a rule of thumb: it has to be implemented whenever a certain type is to be passed as an attribute to a parser normally exposing a STL container and if the type does not expose the interface of a STL container (i.e. no function being equivalent to c.insert(c.end(), attr). These components have an attribute propagation rule in the form:

a: A --> Op(a): vector<A>

where Op(a) stands for any meaningful operation on the component a.

Related Attribute Customization Points

If this customization point is implemented, the following other customization points might need to be implemented as well.

Name	When to implement
`traits::container_value`	Qi: List, Kleene, Plus, Repeat.
`traits::clear_value`	Qi: List, Kleene, Plus, Repeat.

Example

Here is an example showing the default implementation of the traits::container_value customization point provided by the library:

template <typename Container, typename T, typename Enable/* = void*/>
struct push_back_container
{
    static bool call(Container& c, T const& val)
    {
        c.insert(c.end(), val);
        return true;
    }
};

This template is instantiated by the library at the appropriate places while using the supplied container and element types as the template arguments. The member function call() will be called whenever an element has to be added to the supplied container

The following example shows the predefined specialization for unused_type:

template <typename Container>
bool push_back(Container&, unused_type)
{
    return true;
}

which defines an empty member function call().