Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit d7c8a7cf0d.
PrevUpHomeNext

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.

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
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.


PrevUpHomeNext