| 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 */ |
|---|
| 293 | |
|---|
