[/ 
  (C) Copyright Edward Diener 2011-2015
  Distributed under the Boost Software License, Version 1.0.
  (See accompanying file LICENSE_1_0.txt or copy at
  http://www.boost.org/LICENSE_1_0.txt).
]

[section:vmd_modifiers_index Index modifiers]

Index modifiers can be used with the BOOST_VMD_ELEM macro
when identifier modifiers are being used. Index modifiers
take two values:

* BOOST_VMD_RETURN_INDEX, return an index as a number, starting with 0,
of the particular identifier modifier which matched, as part of the
output of the BOOST_VMD_ELEM macro. If no particular identifier modifier
matches, return emptiness as part of the output. The index number is
determined purely by the order in which identifier modifiers are
specified as optional parameters to BOOST_VMD_ELEM, whether singly as
individual optional parameters or as a tuple of identifier modifiers.
* BOOST_VMD_RETURN_NO_INDEX, do not return an index as part of the output.
This is the default value and need only be used to override the 
BOOST_VMD_RETURN_INDEX value if it is specified.

The BOOST_VMD_RETURN_INDEX tells the programmer which one of the identifier
modifiers matched the element's data as an index. Some macro programmers
find this more useful for the purposes of macro branching logic than
branching using the actual name of the identifier itself.

When the index modifier BOOST_VMD_RETURN_INDEX is specified, and identifier
modifiers are specified along with the BOOST_VMD_TYPE_IDENTIFIER filter
modifier, the output of BOOST_VMD_ELEM becomes a tuple of two elements. 
The first tuple element is the element matched and the last tuple element is the 
index, starting with 0, of the identifier modifier which matched. If an element 
is not matched both tuple elements are empty.

If the splitting modifier BOOST_VMD_RETURN_AFTER is also specified then the 
output is a tuple of three elements. The first tuple element is the element matched,
the second tuple element is the rest of the sequence after the matching element,
and the last tuple element is the numeric index. If an element is not matched
then all three tuple elements are empty.

If identifier modifiers and the BOOST_VMD_TYPE_IDENTIFIER filter modifier
are not specified as optional parameters, then if BOOST_VMD_RETURN_INDEX is
specified it is ignored. If the splitting modifier BOOST_VMD_RETURN_ONLY_AFTER
is specified, if BOOST_VMD_RETURN_INDEX is also specified it is ignored.

Let's see how this works:

 #include <boost/vmd/elem.hpp>
 
 #define BOOST_VMD_REGISTER_ANAME (ANAME)
 #define BOOST_VMD_REGISTER_APLACE (APLACE)
 #define BOOST_VMD_REGISTER_ACOUNTRY (ACOUNTRY)
 
 #define BOOST_VMD_DETECT_ANAME_ANAME
 #define BOOST_VMD_DETECT_APLACE_APLACE
 
 #define A_SEQUENCE (1,2,3) ANAME (1)(2) 46
 
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) will return 'ANAME'
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,APLACE,ACOUNTRY) will return emptiness
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,APLACE,ACOUNTRY) will return (,)
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,ANAME,APLACE,ACOUNTRY) will return '(ANAME,0)'
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,(APLACE,ACOUNTRY,ANAME)) will return '(ANAME,2)'
 
Used with splitting modifiers:

 #include <boost/vmd/elem.hpp>
 
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,APLACE,ACOUNTRY,BOOST_VMD_RETURN_AFTER) will return (,,)
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,ANAME,APLACE,ACOUNTRY,BOOST_VMD_RETURN_AFTER) will return '(ANAME,(1)(2) 46,0)'
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,(APLACE,ACOUNTRY,ANAME),BOOST_VMD_RETURN_AFTER) will return '(ANAME,(1)(2) 46,2)'
 
 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,(APLACE,ACOUNTRY,ANAME),BOOST_VMD_RETURN_ONLY_AFTER) will return '(1)(2) 46'

[endsect]