Dereference the Iterator pointing into a Container Attribute

| Home | Libraries | People | FAQ | More

##### Dereference the Iterator pointing into a Container Attribute

###### deref_iterator

The template `deref_iterator` 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 dereference an iterator pointing to an element of a 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 Iterator, typename Enable>
    struct deref_iterator
    {
        typedef <unspecified> type;
        static type call(Iterator& it);
    };

###### Template parameters

Parameter | Description | Default
--- | --- | ---
`Iterator` | The type, `Iterator` of the iterator to dereference. This is the same as the type returned by the customization point `container_iterator`. | none
`Enable` | Helper template parameter usable to selectively enable or disable certain specializations of `deref_iterator` utilizing SFINAE (i.e. `boost::enable_if` or `boost::disable_if`). | `void`

###### Notation

`Iterator`

  An iterator type.

`it`

  An instance of an iterator of type `Iterator`.

`C`

  A container type whose iterator type is `Iterator`.

###### Expression Semantics

Expression | Semantics
--- | ---
`deref_iterator<Iterator>::type` | Metafunction result evaluating to the type returned by dereferencing the iterator.
`deref_iterator<Iterator>::call(it)` | Return the element in the container referred to by the iterator. The type of the returned value is the same as returned by the metafunction result `type`.

###### 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 | Value
--- | ---
`Iterator` | The metafunction result `type` evaluates to `boost::detail::iterator_traits<Iterator>::reference` and the function `call()` returns `*it`.
`unused_type` `const*` | The metafunction result `type` evaluates to `unused_type` and the function `call()` returns `unused`.

###### When to implement

The customization point `deref_iterator` needs to be implemented for a specific iterator type whenever the container this iterator belongs to 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 iterator type belongs to a container which is to be passed as an attribute to a generator normally exposing a STL container, `C` and if the container 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
--- | ---
`is_container` | Needs to be implemented whenever a type is to be used as a container attribute in Karma.
`container_iterator` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`begin_container` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`end_container` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`deref_iterator` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`next_iterator` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.
`compare_iterators` | Karma: List (`%`), Kleene (unary `*`), Plus (unary `+`), Repeat.

###### Example

Here are the header files needed to make the example code below compile:

    #include <boost/spirit/include/karma.hpp>
    #include <iostream>
    #include <vector>

The example (for the full source code please see here: customize_counter.cpp) uses the data structure

    namespace client
    {
        struct counter
        {
            // expose the current value of the counter as our iterator
            typedef int iterator;

            // expose 'int' as the type of each generated element
            typedef int type;

            counter(int max_count)
              : counter_(0), max_count_(max_count)
            {}

            int counter_;
            int max_count_;
        };
    }

as a direct attribute to the List (`%`) generator. This type does not expose any of the interfaces of an STL container. It does not even expose the usual semantics of a container. The presented customization points build a counter instance which is incremented each time it is accessed. The examples shows how to enable its use as an attribute to Karma's repetitive generators.

In order to make this data structure compatible we need to specialize a couple of attribute customization points: `is_container`, `container_iterator`, `begin_container`, and `end_container`. In addition, we specialize one of the iterator related customization points as well: `deref_iterator`.

    // All specializations of attribute customization points have to be placed into
    // the namespace boost::spirit::traits.
    //
    // Note that all templates below are specialized using the 'const' type.
    // This is necessary as all attributes in Karma are 'const'.
    namespace boost { namespace spirit { namespace traits
    {
        // The specialization of the template 'is_container<>' will tell the
        // library to treat the type 'client::counter' as a container providing
        // the items to generate output from.
        template <>
        struct is_container<client::counter const>
          : mpl::true_
        {};

        // The specialization of the template 'container_iterator<>' will be
        // invoked by the library to evaluate the iterator type to be used
        // for iterating the data elements in the container.
        template <>
        struct container_iterator<client::counter const>
        {
            typedef client::counter::iterator type;
        };

        // The specialization of the templates 'begin_container<>' and
        // 'end_container<>' below will be used by the library to get the iterators
        // pointing to the begin and the end of the data to generate output from.
        // These specializations respectively return the initial and maximum
        // counter values.
        //
        // The passed argument refers to the attribute instance passed to the list
        // generator.
        template <>
        struct begin_container<client::counter const>
        {
            static client::counter::iterator
            call(client::counter const& c)
            {
                return c.counter_;
            }
        };

        template <>
        struct end_container<client::counter const>
        {
            static client::counter::iterator
            call(client::counter const& c)
            {
                return c.max_count_;
            }
        };
    }}}

    // All specializations of attribute customization points have to be placed into
    // the namespace boost::spirit::traits.
    namespace boost { namespace spirit { namespace traits
    {
        // The specialization of the template 'deref_iterator<>' will be used to
        // dereference the iterator associated with our counter data structure.
        // Since we expose the current value as the iterator we just return the
        // current iterator as the return value.
        template <>
        struct deref_iterator<client::counter::iterator>
        {
            typedef client::counter::type type;

            static type call(client::counter::iterator const& it)
            {
                return it;
            }
        };
    }}}

The last code snippet shows an example using an instance of the data structure `client::counter` to generate output from a List (`%`) generator:

    // use the instance of a 'client::counter' instead of a STL vector
    client::counter count(4);
    std::cout << karma::format(karma::int_ % ", ", count) << std::endl;   // prints: '0, 1, 2, 3'

As you can see, the specializations for the customization points as defined above enable the seamless integration of the custom data structure without having to modify the output format or the generator itself.

For other examples of how to use the customization point `deref_iterator` please see here: use_as_container.