Index modifiers

| Home | Libraries | People | FAQ | More

### 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'