Compare two Iterator pointing into a Container Attribute for Equality

| Home | Libraries | People | FAQ | More

##### Compare two Iterator pointing into a Container Attribute for Equality

###### compare_iterators

The template `compare_iterators` 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 compare the current iterator (returned either from `begin_container` or from `next_iterator`) with the end iterator (returned from `end_container`) in order to find the end of the element sequence to generate output for.

###### 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 compare_iterators
    {
        static bool call(Iterator const& it1, Iterator const& it2);
    };

###### 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 `compare_iterators` utilizing SFINAE (i.e. `boost::enable_if` or `boost::disable_if`). | `void`

###### Notation

`Iterator`

  An iterator type.

`it1`, `it2`

  Instances of an iterator of type `Iterator`.

`C`

  A container type whose iterator type is `Iterator`.

###### Expression Semantics

Expression | Semantics
--- | ---
`compare_iterators<Iterator>::call(it1, it2)` | Returns whether the iterators `it1` `it2` are to be treated as being equal.

###### 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 function `call()` returns it1 == it2.
`unused_type` `const*` | The function `call()` always returns false.

###### When to implement

The customization point `compare_iterators` 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

For an example of how to use the customization point `compare_iterators` please see here: use_as_container.