]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | |
2 | // (C) Copyright Edward Diener 2011-2015 | |
3 | // Use, modification and distribution are subject to the Boost Software License, | |
4 | // Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at | |
5 | // http://www.boost.org/LICENSE_1_0.txt). | |
6 | ||
7 | #if !defined(BOOST_VMD_ELEM_HPP) | |
8 | #define BOOST_VMD_ELEM_HPP | |
9 | ||
10 | #include <boost/vmd/detail/setup.hpp> | |
11 | ||
12 | #if BOOST_PP_VARIADICS | |
13 | ||
14 | #include <boost/vmd/detail/modifiers.hpp> | |
15 | #include <boost/vmd/detail/sequence_elem.hpp> | |
16 | ||
17 | /* | |
18 | ||
19 | The succeeding comments in this file are in doxygen format. | |
20 | ||
21 | */ | |
22 | ||
23 | /** \file | |
24 | */ | |
25 | ||
26 | /** \def BOOST_VMD_ELEM(elem,...) | |
27 | ||
28 | \brief Accesses an element of a sequence. | |
29 | ||
30 | elem = A sequence element number. From 0 to sequence size - 1. | |
31 | ... = Variadic parameters. | |
32 | ||
33 | The first variadic parameter is required and is the sequence to access. | |
34 | Further variadic parameters are all optional. | |
35 | ||
36 | With no further variadic parameters the macro returns the particular element | |
37 | in the sequence. If the element number is outside the bounds of the sequence | |
38 | macro access fails and the macro turns emptiness. | |
39 | ||
40 | Optional parameters determine what it means that an element is successfully | |
41 | accessed as well as what data is returned by the macro. | |
42 | ||
43 | Filters: specifying a VMD type tells the macro to return the element only | |
44 | if it is of the VMD type specified, else macro access fails. If more than | |
45 | one VMD type is specified as an optional parameter the last one | |
46 | specified is the filter. | |
47 | ||
48 | Matching Identifiers: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER, | |
49 | optional parameters which are identifiers specify that the element accessed | |
50 | must match one of the identifiers else access fails. The identifiers may be specified multiple | |
51 | times as single optional parameters or once as a tuple of identifier | |
52 | parameters. If the identifiers are specified as single optional parameters | |
53 | they cannot be any of the specific BOOST_VMD_ optional parameters in order to be | |
54 | recognized as matching identifiers. Normally this should never be the case. | |
55 | The only situation where this could occur is if the VMD types, which are filters, | |
56 | are used as matching identifiers; in this case the matching identifiers need | |
57 | to be passed as a tuple of identifier parameters so they are not treated | |
58 | as filters. | |
59 | ||
60 | Filters and matching identifiers change what it means that an element is successfully | |
61 | accessed. They do not change what data is returned by the macro. The remaining optional | |
62 | parameters do not change what it means that an element is successfully accessed but they | |
63 | do change what data is returned by the macro. | |
64 | ||
65 | Splitting: Splitting allows the macro to return the rest of the sequence | |
66 | after the element accessed. | |
67 | ||
68 | If BOOST_VMD_RETURN_AFTER is specified the return is a tuple | |
69 | with the element accessed as the first tuple parameter and the rest of | |
70 | the sequence as the second tuple parameter. If element access fails | |
71 | both tuple parameters are empty. | |
72 | ||
73 | If BOOST_VMD_RETURN_ONLY_AFTER | |
74 | is specified the return is the rest of the sequence after the element accessed | |
75 | found. If the element access fails the return is emptiness. | |
76 | ||
77 | If BOOST_VMD_RETURN_NO_AFTER, the default, is specified no splitting | |
78 | occurs. | |
79 | ||
80 | If more than one of the splitting identifiers are specified | |
81 | the last one specified determines the splitting. | |
82 | ||
83 | Return Type: The element accessed can be changed to return both the type | |
84 | of the element as well as the element data with optional return type | |
85 | parameters. When a type is returned, the element accessed which is returned becomes a | |
86 | two-element tuple where the type of the element accessed is the first tuple element and the element | |
87 | data itself is the second tuple element. If the macro fails to access the | |
88 | element the element access returned is emptiness and not a tuple. | |
89 | ||
90 | If BOOST_VMD_RETURN_NO_TYPE, the default, is specified no type is returned | |
91 | as part of the element accessed. | |
92 | ||
93 | If BOOST_VMD_RETURN_TYPE is specified the specific type of the element | |
94 | is returned in the tuple. | |
95 | ||
96 | If BOOST_VMD_RETURN_TYPE_ARRAY is specified | |
97 | an array type is returned if the element is an array, else a tuple | |
98 | type is returned if the element is a tuple, else the actual type | |
99 | is returned for non-tuple data. | |
100 | ||
101 | If BOOST_VMD_RETURN_TYPE_LIST is specified | |
102 | a list type is returned if the element is a list, else a tuple | |
103 | type is returned if the element is a tuple, else the actual type | |
104 | is returned for non-tuple data. | |
105 | ||
106 | If BOOST_VMD_RETURN_TYPE_TUPLE is specified | |
107 | a tuple type is returned for all tuple-like data, else the actual type | |
108 | is returned for non-tuple data. | |
109 | ||
110 | If more than one return type optional | |
111 | parameter is specified the last one specified determines the return type. | |
112 | ||
113 | If a filter is specified optional return type parameters are ignored and | |
114 | the default BOOST_VMD_RETURN_NO_TYPE is in effect. | |
115 | ||
116 | Index: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER, | |
117 | and matching identifiers are specified, an index parameter specifies that the | |
118 | numeric index, starting with 0, of the matching identifier found, be returned | |
119 | as part of the result. | |
120 | ||
121 | If BOOST_VMD_RETURN_INDEX is specified an index is returned | |
122 | as part of the result. | |
123 | ||
124 | If BOOST_VMD_RETURN_NO_INDEX, the default, is specified | |
125 | no index is returned as part of the result. | |
126 | ||
127 | If both are specified the last one specified determines the index parameter. | |
128 | ||
129 | When an index is returned as part of the result, the result is a tuple where the | |
130 | element accessed is the first tuple parameter and the index is the last tuple parameter. | |
131 | If element access fails the index is empty. If there is no BOOST_VMD_TYPE_IDENTIFIER | |
132 | filter or if there are no matching identifiers the BOOST_VMD_RETURN_INDEX is ignored | |
133 | and no index is returned as part of the result. | |
134 | ||
135 | returns = With no optional parameters the element accessed is returned, or emptiness if | |
136 | element is outside the bounds of the sequence. Filters and matching identifiers | |
137 | can change the meaning of whether the element accessed is returned or failure | |
138 | occurs, but whenever failure occurs emptiness is returned as the element access part | |
139 | of that failure, else the element accessed is returned. Return type optional parameters, | |
140 | when filters are not used, return the element accessed as a two-element tuple | |
141 | where the first tuple element is the type and the second tuple element is the | |
142 | data; if the element is not accessed then emptiness is returned as the element access | |
143 | and not a tuple. Splitting with BOOST_VMD_RETURN_AFTER returns a tuple where the element accessed | |
144 | is the first tuple element and the rest of the sequence is the second tuple element. | |
145 | Splitting with BOOST_VMD_RETURN_ONLY_AFTER returns the rest of the sequence after | |
146 | the element accessed or emptiness if the element can not be accessed. Indexing | |
147 | returns the index as part of the output only if filtering with | |
148 | BOOST_VMD_TYPE_IDENTIFIER is specified and matching identifiers are specified. | |
149 | When the index is returned with BOOST_VMD_RETURN_AFTER it is the third element | |
150 | of the tuple returned, else it is the second element of a tuple where the element | |
151 | accessed is the first element of the tuple. | |
152 | ||
153 | */ | |
154 | ||
155 | #define BOOST_VMD_ELEM(elem,...) \ | |
156 | BOOST_VMD_DETAIL_SEQUENCE_ELEM(BOOST_VMD_ALLOW_ALL,elem,__VA_ARGS__) \ | |
157 | /**/ | |
158 | ||
159 | /** \def BOOST_VMD_ELEM_D(d,elem,...) | |
160 | ||
161 | \brief Accesses an element of a sequence. Re-entrant version. | |
162 | ||
163 | d = The next available BOOST_PP_WHILE iteration. | |
164 | elem = A sequence element number. From 0 to sequence size - 1. | |
165 | ... = Variadic parameters. | |
166 | ||
167 | The first variadic parameter is required and is the sequence to access. | |
168 | Further variadic parameters are all optional. | |
169 | ||
170 | With no further variadic parameters the macro returns the particular element | |
171 | in the sequence. If the element number is outside the bounds of the sequence | |
172 | macro access fails and the macro turns emptiness. | |
173 | ||
174 | Optional parameters determine what it means that an element is successfully | |
175 | accessed as well as what data is returned by the macro. | |
176 | ||
177 | Filters: specifying a VMD type tells the macro to return the element only | |
178 | if it is of the VMD type specified, else macro access fails. If more than | |
179 | one VMD type is specified as an optional parameter the last one | |
180 | specified is the filter. | |
181 | ||
182 | Matching Identifiers: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER, | |
183 | optional parameters which are identifiers specify that the element accessed | |
184 | must match one of the identifiers else access fails. The identifiers may be specified multiple | |
185 | times as single optional parameters or once as a tuple of identifier | |
186 | parameters. If the identifiers are specified as single optional parameters | |
187 | they cannot be any of the specific BOOST_VMD_ optional parameters in order to be | |
188 | recognized as matching identifiers. Normally this should never be the case. | |
189 | The only situation where this could occur is if the VMD types, which are filters, | |
190 | are used as matching identifiers; in this case the matching identifiers need | |
191 | to be passed as a tuple of identifier parameters so they are not treated | |
192 | as filters. | |
193 | ||
194 | Filters and matching identifiers change what it means that an element is successfully | |
195 | accessed. They do not change what data is returned by the macro. The remaining optional | |
196 | parameters do not change what it means that an element is successfully accessed but they | |
197 | do change what data is returned by the macro. | |
198 | ||
199 | Splitting: Splitting allows the macro to return the rest of the sequence | |
200 | after the element accessed. | |
201 | ||
202 | If BOOST_VMD_RETURN_AFTER is specified the return is a tuple | |
203 | with the element accessed as the first tuple parameter and the rest of | |
204 | the sequence as the second tuple parameter. If element access fails | |
205 | both tuple parameters are empty. | |
206 | ||
207 | If BOOST_VMD_RETURN_ONLY_AFTER | |
208 | is specified the return is the rest of the sequence after the element accessed | |
209 | found. If the element access fails the return is emptiness. | |
210 | ||
211 | If BOOST_VMD_RETURN_NO_AFTER, the default, is specified no splitting | |
212 | occurs. | |
213 | ||
214 | If more than one of the splitting identifiers are specified | |
215 | the last one specified determines the splitting. | |
216 | ||
217 | Return Type: The element accessed can be changed to return both the type | |
218 | of the element as well as the element data with optional return type | |
219 | parameters. When a type is returned, the element accessed which is returned becomes a | |
220 | two-element tuple where the type of the element accessed is the first tuple element and the element | |
221 | data itself is the second tuple element. If the macro fails to access the | |
222 | element the element access returned is emptiness and not a tuple. | |
223 | ||
224 | If BOOST_VMD_RETURN_NO_TYPE, the default, is specified no type is returned | |
225 | as part of the element accessed. | |
226 | ||
227 | If BOOST_VMD_RETURN_TYPE is specified the specific type of the element | |
228 | is returned in the tuple. | |
229 | ||
230 | If BOOST_VMD_RETURN_TYPE_ARRAY is specified | |
231 | an array type is returned if the element is an array, else a tuple | |
232 | type is returned if the element is a tuple, else the actual type | |
233 | is returned for non-tuple data. | |
234 | ||
235 | If BOOST_VMD_RETURN_TYPE_LIST is specified | |
236 | a list type is returned if the element is a list, else a tuple | |
237 | type is returned if the element is a tuple, else the actual type | |
238 | is returned for non-tuple data. | |
239 | ||
240 | If BOOST_VMD_RETURN_TYPE_TUPLE is specified | |
241 | a tuple type is returned for all tuple-like data, else the actual type | |
242 | is returned for non-tuple data. If more than one return type optional | |
243 | parameter is specified the last one specified determines the return type. | |
244 | ||
245 | If a filter is specified optional return type parameters are ignored and | |
246 | the default BOOST_VMD_RETURN_NO_TYPE is in effect. | |
247 | ||
248 | Index: If the filter is specified as the identifier type, BOOST_VMD_TYPE_IDENTIFIER, | |
249 | and matching identifiers are specified, an index parameter specifies that the | |
250 | numeric index, starting with 0, of the matching identifier found, be returned | |
251 | as part of the result. | |
252 | ||
253 | If BOOST_VMD_RETURN_INDEX is specified an index is returned | |
254 | as part of the result. | |
255 | ||
256 | If BOOST_VMD_RETURN_NO_INDEX, the default, is specified | |
257 | no index is returned as part of the result. | |
258 | ||
259 | If both are specified the last one specified determines the index parameter. | |
260 | ||
261 | When an index is returned as part of the result, the result is a tuple where the | |
262 | element accessed is the first tuple parameter and the index is the last tuple parameter. | |
263 | If element access fails the index is empty. If there is no BOOST_VMD_TYPE_IDENTIFIER | |
264 | filter or if there are no matching identifiers the BOOST_VMD_RETURN_INDEX is ignored | |
265 | and no index is returned as part of the result. | |
266 | ||
267 | returns = With no optional parameters the element accessed is returned, or emptiness if | |
268 | element is outside the bounds of the sequence. Filters and matching identifiers | |
269 | can change the meaning of whether the element accessed is returned or failure | |
270 | occurs, but whenever failure occurs emptiness is returned as the element access part | |
271 | of that failure, else the element accessed is returned. Return type optional parameters, | |
272 | when filters are not used, return the element accessed as a two-element tuple | |
273 | where the first tuple element is the type and the second tuple element is the | |
274 | data; if the element is not accessed then emptiness is returned as the element access | |
275 | and not a tuple. Splitting with BOOST_VMD_RETURN_AFTER returns a tuple where the element accessed | |
276 | is the first tuple element and the rest of the sequence is the second tuple element. | |
277 | Splitting with BOOST_VMD_RETURN_ONLY_AFTER returns the rest of the sequence after | |
278 | the element accessed or emptiness if the element can not be accessed. Indexing | |
279 | returns the index as part of the output only if filtering with | |
280 | BOOST_VMD_TYPE_IDENTIFIER is specified and matching identifiers are specified. | |
281 | When the index is returned with BOOST_VMD_RETURN_AFTER it is the third element | |
282 | of the tuple returned, else it is the second element of a tuple where the element | |
283 | accessed is the first element of the tuple. | |
284 | ||
285 | */ | |
286 | ||
287 | #define BOOST_VMD_ELEM_D(d,elem,...) \ | |
288 | BOOST_VMD_DETAIL_SEQUENCE_ELEM_D(d,BOOST_VMD_ALLOW_ALL,elem,__VA_ARGS__) \ | |
289 | /**/ | |
290 | ||
291 | #endif /* BOOST_PP_VARIADICS */ | |
292 | #endif /* BOOST_VMD_ELEM_HPP */ |