1[/ 2 (C) Copyright Edward Diener 2011-2015 3 Distributed under the Boost Software License, Version 1.0. 4 (See accompanying file LICENSE_1_0.txt or copy at 5 http://www.boost.org/LICENSE_1_0.txt). 6] 7 8[section:vmd_modifiers_identifier Identifier modifiers] 9 10Identifier modifiers are optional parameters which 11specify a set of identifiers to search in order to look 12for a particular identifier match rather than just any 13identifier. 14 15[heading Usage with BOOST_VMD_IS_IDENTIFIER] 16 17Once we have both registered and pre-detected an identifier we can test whether 18an identifier is a particular identifier using BOOST_VMD_IS_IDENTIFER and 19identifier modifiers. We do this by passing optional parameter(s) to 20BOOST_VMD_IS_IDENTIFER. The optional parameter(s) are either a single tuple of 21possible identifiers we are trying to match, or the individual identifiers 22themselves as separate parameters. 23 24Using the optional parameter(s) with BOOST_VMD_IS_IDENTIFER we are asking 25not only if our input is any of the registered identifiers but also if it is one 26of a number of pre-detected identifiers. 27 28As an example: 29 30 #include <boost/vmd/is_identifier.hpp> 31 32 #define BOOST_VMD_REGISTER_yellow (yellow) 33 #define BOOST_VMD_REGISTER_green (green) 34 #define BOOST_VMD_REGISTER_blue (blue) 35 #define BOOST_VMD_REGISTER_red (red) 36 37 #define BOOST_VMD_DETECT_yellow_yellow 38 #define BOOST_VMD_DETECT_green_green 39 #define BOOST_VMD_DETECT_blue_blue 40 41 BOOST_VMD_IS_IDENTIFIER(some_input,yellow) // returns 1 only if 'some_input is 'yellow', else returns 0 42 BOOST_VMD_IS_IDENTIFIER(some_input,yellow,blue) // returns 1 only if 'some_input is 'yellow' or 'blue', else returns 0 43 BOOST_VMD_IS_IDENTIFIER(some_input,(yellow,green)) // returns 1 if 'some_input' is 'yellow' or 'green', else returns 0 44 45 BOOST_VMD_IS_IDENTIFIER(some_input,red) 46 // always returns 0, even if 'some_input' is 'red' since 'red' has not been pre-detected 47 48whereas 49 50 BOOST_VMD_IS_IDENTIFIER(some_input) // returns 1 if 'some_input' is 'red' since 'red' has been registered 51 52If you invoke BOOST_VMD_IS_IDENTIFIER with the optional parameter(s), the invocation will 53only return 1 if the input matches one the identifier(s) of the optional parameters and the 54identifier it matches has been registered and pre-detected. 55 56Both VMD numbers and v-types are identifier subtypes so you can also use them 57as identifier modifiers. You do not have to register or pre-detect VMD numbers 58or v-types since VMD has already done that for you. 59 60As an example of using VMD numbers or v-types as identifier modifiers with BOOST_VMD_IS_IDENTIFIER: 61 62 BOOST_VMD_IS_IDENTIFIER(some_input,1,3,5) // returns 1 only if 'some_input' is 1 or 3 or 5, else returns 0 63 BOOST_VMD_IS_IDENTIFIER(some_input,BOOST_VMD_TYPE_TUPLE,BOOST_VMD_TYPE_LIST,59) 64 // returns 1 only if 'some_input is the v-type BOOST_VMD_TYPE_TUPLE or the v-type BOOST_VMD_TYPE_LIST or 59, else returns 0 65 66 67[heading Usage with BOOST_VMD_ELEM] 68 69When we use the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER as an optional 70parameter of BOOST_VMD_ELEM we are asking for a particular element of a sequence 71as long as it is a VMD identifier. With that specific filter modifier 72BOOST_VMD_TYPE_IDENTIFIER we can use identifier modifiers to ask for a particular 73element of a sequence as long as it matches one of our identifier modifiers. If 74the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER is not being used then all 75identifier modifiers are ignored. 76 77The syntax for specifying identifier modifiers using BOOST_VMD_ELEM is 78exactly the same as the equivalent feature of the BOOST_VMD_IS_IDENTIFIER 79macro explained just previously. Optional parameters in the form of 80identifiers can be specified either singly any number of times or once 81as part of a tuple. For an identifier found as a sequence element to 82match against one of these possible identifiers, the possible 83identifiers must be both registered and pre-detected. 84 85Since filter modifiers, which are v-types, are also identifiers, if 86you want to use v-types as identifier modifiers you must use the form 87which places all identifier modifiers as part of a tuple. Otherwise any 88v-types specified singly as optional parameters are seen as filter 89modifiers and never as identifier modifiers. VMD numbers are also identifiers 90and may be used as identifier modifiers, but in this case VMD numbers as 91identifier modifiers do not need to be part of a tuple to be detected. 92 93Let's see how this works: 94 95 #include <boost/vmd/elem.hpp> 96 97 #define BOOST_VMD_REGISTER_ANAME (ANAME) 98 #define BOOST_VMD_REGISTER_APLACE (APLACE) 99 #define BOOST_VMD_REGISTER_ACOUNTRY (ACOUNTRY) 100 101 #define BOOST_VMD_DETECT_ANAME_ANAME 102 #define BOOST_VMD_DETECT_APLACE_APLACE 103 104 #define A_SEQUENCE (1,2,3) ANAME 46 BOOST_VMD_TYPE_SEQ ACOUNTRY 105 106 BOOST_VMD_ELEM(1,A_SEQUENCE) will return 'ANAME' 107 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) will return 'ANAME' 108 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,APLACE,ACOUNTRY) will return emptiness 109 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,ANAME,APLACE,ACOUNTRY) will return 'ANAME' 110 BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,(APLACE,ACOUNTRY,ANAME)) will return 'ANAME' 111 112 BOOST_VMD_ELEM(4,A_SEQUENCE) will return 'ACOUNTRY' 113 BOOST_VMD_ELEM(4,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) will return 'ACOUNTRY' 114 BOOST_VMD_ELEM(4,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,ACOUNTRY,ANAME) 115 will return emptiness since ACOUNTRY is not pre-detected 116 117Let us illustrate the case where VMD identifiers can be represented as either 118filter modifiers or identifier modifiers. 119 120Using the sequence above: 121 122 #include <boost/vmd/elem.hpp> 123 124 BOOST_VMD_ELEM(3,A_SEQUENCE) will return the BOOST_VMD_TYPE_SEQ type 125 BOOST_VMD_ELEM(3,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) 126 will return the BOOST_VMD_TYPE_SEQ type since a type is an identifier 127 BOOST_VMD_ELEM(3,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_TYPE_SEQ,BOOST_VMD_TYPE_TUPLE) will return emptiness 128 129The last use of our macro returns emptiness because if there is more than one 130type specified as an optional parameter the last type is chosen for filtering. 131Since the last type for type filtering is BOOST_VMD_TYPE_TUPLE and our fourth 132element is a v-type and not a tuple, emptiness is returned. The syntax does not 133specifying filtering with identifiers as might be supposed since BOOST_VMD_TYPE_SEQ 134and BOOST_VMD_TYPE_TUPLE are not treated as identifier modifiers but rather as 135additional filter modifiers. 136 137In order to do filtering with an identifier and do it against 138various types themselves, since v-types are identifiers, we must 139use the tuple form to specify our identifier modifiers: 140 141 #include <boost/vmd/elem.hpp> 142 143 BOOST_VMD_ELEM(3,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,(BOOST_VMD_TYPE_SEQ,BOOST_VMD_TYPE_TUPLE)) 144 will return BOOST_VMD_TYPE_SEQ 145 146Now BOOST_VMD_TYPE_SEQ and BOOST_VMD_TYPE_TUPLE are treated as identifiers 147modifiers to match against. 148 149[endsect]