ceph/src/boost/libs/vmd/doc/vmd_modifiers_index.qbk

   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_index Index modifiers]
   9
  10 Index modifiers can be used with the BOOST_VMD_ELEM macro
  11 when identifier modifiers are being used. Index modifiers
  12 take two values:
  13
  14 * BOOST_VMD_RETURN_INDEX, return an index as a number, starting with 0,
  15 of the particular identifier modifier which matched, as part of the
  16 output of the BOOST_VMD_ELEM macro. If no particular identifier modifier
  17 matches, return emptiness as part of the output. The index number is
  18 determined purely by the order in which identifier modifiers are
  19 specified as optional parameters to BOOST_VMD_ELEM, whether singly as
  20 individual optional parameters or as a tuple of identifier modifiers.
  21 * BOOST_VMD_RETURN_NO_INDEX, do not return an index as part of the output.
  22 This is the default value and need only be used to override the
  23 BOOST_VMD_RETURN_INDEX value if it is specified.
  24
  25 The BOOST_VMD_RETURN_INDEX tells the programmer which one of the identifier
  26 modifiers matched the element's data as an index. Some macro programmers
  27 find this more useful for the purposes of macro branching logic than
  28 branching using the actual name of the identifier itself.
  29
  30 When the index modifier BOOST_VMD_RETURN_INDEX is specified, and identifier
  31 modifiers are specified along with the BOOST_VMD_TYPE_IDENTIFIER filter
  32 modifier, the output of BOOST_VMD_ELEM becomes a tuple of two elements.
  33 The first tuple element is the element matched and the last tuple element is the
  34 index, starting with 0, of the identifier modifier which matched. If an element
  35 is not matched both tuple elements are empty.
  36
  37 If the splitting modifier BOOST_VMD_RETURN_AFTER is also specified then the
  38 output is a tuple of three elements. The first tuple element is the element matched,
  39 the second tuple element is the rest of the sequence after the matching element,
  40 and the last tuple element is the numeric index. If an element is not matched
  41 then all three tuple elements are empty.
  42
  43 If identifier modifiers and the BOOST_VMD_TYPE_IDENTIFIER filter modifier
  44 are not specified as optional parameters, then if BOOST_VMD_RETURN_INDEX is
  45 specified it is ignored. If the splitting modifier BOOST_VMD_RETURN_ONLY_AFTER
  46 is specified, if BOOST_VMD_RETURN_INDEX is also specified it is ignored.
  47
  48 Let's see how this works:
  49
  50  #include <boost/vmd/elem.hpp>
  51
  52  #define BOOST_VMD_REGISTER_ANAME (ANAME)
  53  #define BOOST_VMD_REGISTER_APLACE (APLACE)
  54  #define BOOST_VMD_REGISTER_ACOUNTRY (ACOUNTRY)
  55
  56  #define BOOST_VMD_DETECT_ANAME_ANAME
  57  #define BOOST_VMD_DETECT_APLACE_APLACE
  58
  59  #define A_SEQUENCE (1,2,3) ANAME (1)(2) 46
  60
  61  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) will return 'ANAME'
  62  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,APLACE,ACOUNTRY) will return emptiness
  63  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,APLACE,ACOUNTRY) will return (,)
  64  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,ANAME,APLACE,ACOUNTRY) will return '(ANAME,0)'
  65  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,(APLACE,ACOUNTRY,ANAME)) will return '(ANAME,2)'
  66
  67 Used with splitting modifiers:
  68
  69  #include <boost/vmd/elem.hpp>
  70
  71  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,APLACE,ACOUNTRY,BOOST_VMD_RETURN_AFTER) will return (,,)
  72  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,ANAME,APLACE,ACOUNTRY,BOOST_VMD_RETURN_AFTER) will return '(ANAME,(1)(2) 46,0)'
  73  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,(APLACE,ACOUNTRY,ANAME),BOOST_VMD_RETURN_AFTER) will return '(ANAME,(1)(2) 46,2)'
  74
  75  BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_RETURN_INDEX,(APLACE,ACOUNTRY,ANAME),BOOST_VMD_RETURN_ONLY_AFTER) will return '(1)(2) 46'
  76
  77 [endsect]