123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149 |
- [/
- (C) Copyright Edward Diener 2011-2015
- Distributed under the Boost Software License, Version 1.0.
- (See accompanying file LICENSE_1_0.txt or copy at
- http://www.boost.org/LICENSE_1_0.txt).
- ]
- [section:vmd_modifiers_identifier Identifier modifiers]
- Identifier modifiers are optional parameters which
- specify a set of identifiers to search in order to look
- for a particular identifier match rather than just any
- identifier.
- [heading Usage with BOOST_VMD_IS_IDENTIFIER]
- Once we have both registered and pre-detected an identifier we can test whether
- an identifier is a particular identifier using BOOST_VMD_IS_IDENTIFER and
- identifier modifiers. We do this by passing optional parameter(s) to
- BOOST_VMD_IS_IDENTIFER. The optional parameter(s) are either a single tuple of
- possible identifiers we are trying to match, or the individual identifiers
- themselves as separate parameters.
- Using the optional parameter(s) with BOOST_VMD_IS_IDENTIFER we are asking
- not only if our input is any of the registered identifiers but also if it is one
- of a number of pre-detected identifiers.
- As an example:
- #include <boost/vmd/is_identifier.hpp>
-
- #define BOOST_VMD_REGISTER_yellow (yellow)
- #define BOOST_VMD_REGISTER_green (green)
- #define BOOST_VMD_REGISTER_blue (blue)
- #define BOOST_VMD_REGISTER_red (red)
-
- #define BOOST_VMD_DETECT_yellow_yellow
- #define BOOST_VMD_DETECT_green_green
- #define BOOST_VMD_DETECT_blue_blue
-
- BOOST_VMD_IS_IDENTIFIER(some_input,yellow) // returns 1 only if 'some_input is 'yellow', else returns 0
- BOOST_VMD_IS_IDENTIFIER(some_input,yellow,blue) // returns 1 only if 'some_input is 'yellow' or 'blue', else returns 0
- BOOST_VMD_IS_IDENTIFIER(some_input,(yellow,green)) // returns 1 if 'some_input' is 'yellow' or 'green', else returns 0
-
- BOOST_VMD_IS_IDENTIFIER(some_input,red)
- // always returns 0, even if 'some_input' is 'red' since 'red' has not been pre-detected
- whereas
-
- BOOST_VMD_IS_IDENTIFIER(some_input) // returns 1 if 'some_input' is 'red' since 'red' has been registered
-
- If you invoke BOOST_VMD_IS_IDENTIFIER with the optional parameter(s), the invocation will
- only return 1 if the input matches one the identifier(s) of the optional parameters and the
- identifier it matches has been registered and pre-detected.
- Both VMD numbers and v-types are identifier subtypes so you can also use them
- as identifier modifiers. You do not have to register or pre-detect VMD numbers
- or v-types since VMD has already done that for you.
- As an example of using VMD numbers or v-types as identifier modifiers with BOOST_VMD_IS_IDENTIFIER:
- BOOST_VMD_IS_IDENTIFIER(some_input,1,3,5) // returns 1 only if 'some_input' is 1 or 3 or 5, else returns 0
- BOOST_VMD_IS_IDENTIFIER(some_input,BOOST_VMD_TYPE_TUPLE,BOOST_VMD_TYPE_LIST,59)
- // 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
- [heading Usage with BOOST_VMD_ELEM]
- When we use the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER as an optional
- parameter of BOOST_VMD_ELEM we are asking for a particular element of a sequence
- as long as it is a VMD identifier. With that specific filter modifier
- BOOST_VMD_TYPE_IDENTIFIER we can use identifier modifiers to ask for a particular
- element of a sequence as long as it matches one of our identifier modifiers. If
- the specific filter modifier BOOST_VMD_TYPE_IDENTIFIER is not being used then all
- identifier modifiers are ignored.
- The syntax for specifying identifier modifiers using BOOST_VMD_ELEM is
- exactly the same as the equivalent feature of the BOOST_VMD_IS_IDENTIFIER
- macro explained just previously. Optional parameters in the form of
- identifiers can be specified either singly any number of times or once
- as part of a tuple. For an identifier found as a sequence element to
- match against one of these possible identifiers, the possible
- identifiers must be both registered and pre-detected.
- Since filter modifiers, which are v-types, are also identifiers, if
- you want to use v-types as identifier modifiers you must use the form
- which places all identifier modifiers as part of a tuple. Otherwise any
- v-types specified singly as optional parameters are seen as filter
- modifiers and never as identifier modifiers. VMD numbers are also identifiers
- and may be used as identifier modifiers, but in this case VMD numbers as
- identifier modifiers do not need to be part of a tuple to be detected.
- Let's see how this works:
- #include <boost/vmd/elem.hpp>
-
- #define BOOST_VMD_REGISTER_ANAME (ANAME)
- #define BOOST_VMD_REGISTER_APLACE (APLACE)
- #define BOOST_VMD_REGISTER_ACOUNTRY (ACOUNTRY)
-
- #define BOOST_VMD_DETECT_ANAME_ANAME
- #define BOOST_VMD_DETECT_APLACE_APLACE
-
- #define A_SEQUENCE (1,2,3) ANAME 46 BOOST_VMD_TYPE_SEQ ACOUNTRY
- BOOST_VMD_ELEM(1,A_SEQUENCE) will return 'ANAME'
- BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) will return 'ANAME'
- BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,APLACE,ACOUNTRY) will return emptiness
- BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,ANAME,APLACE,ACOUNTRY) will return 'ANAME'
- BOOST_VMD_ELEM(1,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,(APLACE,ACOUNTRY,ANAME)) will return 'ANAME'
-
- BOOST_VMD_ELEM(4,A_SEQUENCE) will return 'ACOUNTRY'
- BOOST_VMD_ELEM(4,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER) will return 'ACOUNTRY'
- BOOST_VMD_ELEM(4,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,ACOUNTRY,ANAME)
- will return emptiness since ACOUNTRY is not pre-detected
-
- Let us illustrate the case where VMD identifiers can be represented as either
- filter modifiers or identifier modifiers.
- Using the sequence above:
- #include <boost/vmd/elem.hpp>
-
- BOOST_VMD_ELEM(3,A_SEQUENCE) will return the BOOST_VMD_TYPE_SEQ type
- BOOST_VMD_ELEM(3,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER)
- will return the BOOST_VMD_TYPE_SEQ type since a type is an identifier
- BOOST_VMD_ELEM(3,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,BOOST_VMD_TYPE_SEQ,BOOST_VMD_TYPE_TUPLE) will return emptiness
-
- The last use of our macro returns emptiness because if there is more than one
- type specified as an optional parameter the last type is chosen for filtering.
- Since the last type for type filtering is BOOST_VMD_TYPE_TUPLE and our fourth
- element is a v-type and not a tuple, emptiness is returned. The syntax does not
- specifying filtering with identifiers as might be supposed since BOOST_VMD_TYPE_SEQ
- and BOOST_VMD_TYPE_TUPLE are not treated as identifier modifiers but rather as
- additional filter modifiers.
- In order to do filtering with an identifier and do it against
- various types themselves, since v-types are identifiers, we must
- use the tuple form to specify our identifier modifiers:
-
- #include <boost/vmd/elem.hpp>
-
- BOOST_VMD_ELEM(3,A_SEQUENCE,BOOST_VMD_TYPE_IDENTIFIER,(BOOST_VMD_TYPE_SEQ,BOOST_VMD_TYPE_TUPLE))
- will return BOOST_VMD_TYPE_SEQ
-
- Now BOOST_VMD_TYPE_SEQ and BOOST_VMD_TYPE_TUPLE are treated as identifiers
- modifiers to match against.
- [endsect]
|