ceph/src/boost/libs/vmd/doc/vmd_modifiers_identifier.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_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]