ceph/src/boost/libs/vmd/doc/vmd_identifying.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_identifying Identifying data types]
   9
  10 [heading Identifying macros and BOOST_VMD_IS_EMPTY ]
  11
  12 The various macros for identifying VMD data types complement
  13 the ability to identify emptiness using BOOST_VMD_IS_EMPTY.
  14 The general name I will use in this documentation for these
  15 specific macros is "identifying macros." The identifying macros
  16 also share with BOOST_VMD_IS_EMPTY the inherent flaw
  17 mentioned when discussing BOOST_VMD_IS_EMPTY, since they themselves
  18 use BOOST_VMD_IS_EMPTY to determine that the input has ended.
  19
  20 To recapitulate the flaw with BOOST_VMD_IS_EMPTY:
  21
  22 * using a standard C++ compiler if the input ends with the
  23 name of a function-like macro, and that macro takes two or
  24 more parameters, a preprocessing error will occur.
  25 * using the VC++ compiler if the input consists of the name
  26 of a function-like macro, and that macro when invoked with no
  27 parameters returns a tuple, the macro erroneously returns 1,
  28 meaning that the input is empty.
  29 * even if the function-like macro takes one parameter, passing
  30 emptiness to that macro could cause a preprocessing error.
  31
  32 The obvious way to avoid the BOOST_VMD_IS_EMPTY problem with the
  33 identifying macros is to design input so that the name of a function-like
  34 macro is never passed as a parameter. This can be done, if one uses
  35 VMD and has situations where the input could contain
  36 a function-like macro name, by having that function-like macro name placed
  37 within a Boost PP data type, such as a tuple, without attempting to identify
  38 the type of the tuple element using VMD. In other word if the input is:
  39
  40  ( SOME_FUNCTION_MACRO_NAME )
  41
  42 and we have the macro definition:
  43
  44  #define SOME_FUNCTION_MACRO_NAME(x,y) some_output
  45
  46 VMD can still parse the input as a tuple, if desired, using BOOST_VMD_IS_TUPLE
  47 without encountering the BOOST_VMD_IS_EMPTY problem. However if the input is:
  48
  49  SOME_FUNCTION_MACRO_NAME
  50
  51 either directly or through accessing the above tuple's first element, and the
  52 programmer attempts to use BOOST_VMD_IS_IDENTIFIER with this input, the
  53 BOOST_VMD_IS_EMPTY problem will occur.
  54
  55 [heading Identifying macros and programming flexibility ]
  56
  57 The VMD identifying macros give the preprocessor metaprogrammer a great amount
  58 of flexibility when designing macros. It is not merely the flexibility of allowing
  59 direct parameters to a macro to be different data types, and having the macro work
  60 differently depending on the type of data passed to it, but it is also the flexibility
  61 of allowing individual elements of the higher level Boost PP data types to be
  62 different data types and have the macro work correctly depending on the type of data
  63 type passed as part of those elements.
  64
  65 With this flexibility also comes a greater amount of responsibility. For the macro
  66 designer this responsibility is twofold:
  67
  68 * To carefully document the possible combinations of acceptable data and what they mean.
  69 * To balance flexibility with ease of use so that the macro does not become so hard to
  70 understand that the programmer invoking the macro gives up using it entirely.
  71
  72 For the programmer invoking a macro the responsibility is to understand the documentation
  73 and not attempt to pass to the macro data which may cause incorrect results or preprocessing
  74 errors.
  75
  76 [endsect]