ceph/src/boost/libs/vmd/include/boost/vmd/elem.hpp

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