]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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 | ||
10 | Identifier modifiers are optional parameters which | |
11 | specify a set of identifiers to search in order to look | |
12 | for a particular identifier match rather than just any | |
13 | identifier. | |
14 | ||
15 | [heading Usage with BOOST_VMD_IS_IDENTIFIER] | |
16 | ||
17 | Once we have both registered and pre-detected an identifier we can test whether | |
18 | an identifier is a particular identifier using BOOST_VMD_IS_IDENTIFER and | |
19 | identifier modifiers. We do this by passing optional parameter(s) to | |
20 | BOOST_VMD_IS_IDENTIFER. The optional parameter(s) are either a single tuple of | |
21 | possible identifiers we are trying to match, or the individual identifiers | |
22 | themselves as separate parameters. | |
23 | ||
24 | Using the optional parameter(s) with BOOST_VMD_IS_IDENTIFER we are asking | |
25 | not only if our input is any of the registered identifiers but also if it is one | |
26 | of a number of pre-detected identifiers. | |
27 | ||
28 | As 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 | ||
48 | whereas | |
49 | ||
50 | BOOST_VMD_IS_IDENTIFIER(some_input) // returns 1 if 'some_input' is 'red' since 'red' has been registered | |
51 | ||
52 | If you invoke BOOST_VMD_IS_IDENTIFIER with the optional parameter(s), the invocation will | |
53 | only return 1 if the input matches one the identifier(s) of the optional parameters and the | |
54 | identifier it matches has been registered and pre-detected. | |
55 | ||
56 | Both VMD numbers and v-types are identifier subtypes so you can also use them | |
57 | as identifier modifiers. You do not have to register or pre-detect VMD numbers | |
58 | or v-types since VMD has already done that for you. | |
59 | ||
60 | As 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 | ||
69 | When we use the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER as an optional | |
70 | parameter of BOOST_VMD_ELEM we are asking for a particular element of a sequence | |
71 | as long as it is a VMD identifier. With that specific filter modifier | |
72 | BOOST_VMD_TYPE_IDENTIFIER we can use identifier modifiers to ask for a particular | |
73 | element of a sequence as long as it matches one of our identifier modifiers. If | |
74 | the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER is not being used then all | |
75 | identifier modifiers are ignored. | |
76 | ||
77 | The syntax for specifying identifier modifiers using BOOST_VMD_ELEM is | |
78 | exactly the same as the equivalent feature of the BOOST_VMD_IS_IDENTIFIER | |
79 | macro explained just previously. Optional parameters in the form of | |
80 | identifiers can be specified either singly any number of times or once | |
81 | as part of a tuple. For an identifier found as a sequence element to | |
82 | match against one of these possible identifiers, the possible | |
83 | identifiers must be both registered and pre-detected. | |
84 | ||
85 | Since filter modifiers, which are v-types, are also identifiers, if | |
86 | you want to use v-types as identifier modifiers you must use the form | |
87 | which places all identifier modifiers as part of a tuple. Otherwise any | |
88 | v-types specified singly as optional parameters are seen as filter | |
89 | modifiers and never as identifier modifiers. VMD numbers are also identifiers | |
90 | and may be used as identifier modifiers, but in this case VMD numbers as | |
91 | identifier modifiers do not need to be part of a tuple to be detected. | |
92 | ||
93 | Let'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 | ||
117 | Let us illustrate the case where VMD identifiers can be represented as either | |
118 | filter modifiers or identifier modifiers. | |
119 | ||
120 | Using 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 | ||
129 | The last use of our macro returns emptiness because if there is more than one | |
130 | type specified as an optional parameter the last type is chosen for filtering. | |
131 | Since the last type for type filtering is BOOST_VMD_TYPE_TUPLE and our fourth | |
132 | element is a v-type and not a tuple, emptiness is returned. The syntax does not | |
133 | specifying filtering with identifiers as might be supposed since BOOST_VMD_TYPE_SEQ | |
134 | and BOOST_VMD_TYPE_TUPLE are not treated as identifier modifiers but rather as | |
135 | additional filter modifiers. | |
136 | ||
137 | In order to do filtering with an identifier and do it against | |
138 | various types themselves, since v-types are identifiers, we must | |
139 | use 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 | ||
146 | Now BOOST_VMD_TYPE_SEQ and BOOST_VMD_TYPE_TUPLE are treated as identifiers | |
147 | modifiers to match against. | |
148 | ||
149 | [endsect] |