Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Click here to view the latest version of this page.
PrevUpHomeNext
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] 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:

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.


PrevUpHomeNext