| Home | Libraries | People | FAQ | More

##### Get the Iterator pointing to the Begin of a Container Attribute

###### begin_container

The template `begin_container` is a type used as an attribute customization point. It is invoked by the Karma repetitive generators (such as List (`%`), Kleene (unary `*`), Plus (unary `+`), and Repeat) in order to get an iterator pointing to the first element of the container holding the attributes to generate output from.

###### 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 Enable>
    struct begin_container
    {
        static typename container_iterator<Container>::type
        call(Container& c);
    };

###### Template parameters

Parameter | Description | Default
--- | --- | ---
`Container` | The type, `Container` for which the iterator pointing to the first element has to be returned | none
`Enable` | Helper template parameter usable to selectively enable or disable certain specializations of `begin_container` utilizing SFINAE (i.e. `boost::enable_if` or `boost::disable_if`). | `void`

Notation

`C`

  A container type the begin iterator needs to be returned for.

`c`

  An instance of a container, `C`.

###### Expression Semantics

Expression | Semantics
--- | ---
`begin_container<C>::call(c)` | Return the iterator usable to dereference the first element of the given container, `c`. The type of the returned iterator is expected to be the same as the type returned by the customization point `traits::container_iterator`.

The returned instance conceptually needs to be equivalent to a standard forward iterator. But it does not have to expose the standardized interface. If this customization point is implemented for a certain container type, all related customization points need to be implemented as well (see Related Attribute Customization Points below). This encapsulates the specific iterator interface required for a given type. The minimal requirements for a type to be exposed as an iterator in this context are:

- it needs to be comparable for equality (see `traits::compare_iterators`),
- it needs to be incrementable (see `traits::next_iterator`),
- it needs to be dereferencible (see `traits::deref_iterator`).

###### Predefined Specializations

Spirit predefines specializations of this customization point for several types. The following table lists those types together with the types returned by the embedded typedef `type`:

Template Parameters | Semantics
--- | ---
`C` | Returns `c.begin()`.
`C const` | Returns `c.begin()`.
`unused_type` | Returns `&unused`.

###### When to implement

The customization point `begin_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 generators (Spirit.Karma) only. As a rule of thumb: it has to be implemented whenever a certain type is to be passed as an attribute to a generator normally exposing a STL container, `C` and if the type does not expose the interface of a STL container (i.e. `is_container<C>::type` would normally return `mpl::false_`).

###### 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::is_container` | Needs to be implemented whenever a type is to be used as a container attribute in Karma.
`traits::container_iterator` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`traits::begin_container` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`traits::end_container` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`traits::deref_iterator` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`traits::next_iterator` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`traits::compare_iterators` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.

###### Example

For examples of how to use the customization point `begin_container` please see here: embedded_container_example, use_as_container, and counter_example.