EQ2EMu/EQ2/source/depends/boost_1_72_0/libs/vmd/doc/vmd_data_types.qbk

[/ 
  (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_data_types Data types]

The VMD library has functionality for testing and parsing preprocessor data.

The C++ preprocessor defines preprocessor data as preprocessing tokens.
The types of preprocessing tokens can be seen in section 2.5 of the C++ standard document.

The VMD library works with a subset of two of these types of preprocessor tokens 
as "data types". These are the "identifier" and "pp-number" preprocessor tokens.
The preprocessor token types which VMD cannot parse are:

* header-name
* character-literal
* user-defined-characteral-literal
* string-literal
* user-defined-string-literal
* preprocessing-op-or-punc

Even though VMD cannot parse these preprocessor token types, it is still
a very useful library since a large part of macro programming works with
'identifier' and 'pp-number' tokens.

VMD identifiers are preprocessing tokens consisting 
of alphanumeric characters and the underscore ( _ ) character. This is very similar to a 
preprocessor token "identifier" with the difference being that a VMD identifier can start with a 
numeric character, allowing VMD identifiers to also be positive integral literals. VMD offers
functionality for parsing VMD identifiers both as a separate element or in a sequence of preprocessing 
tokens.

VMD numbers are Boost PP numbers, ie. preprocessing tokens of 
whole numbers between 0 and 256 inclusive. These are a small subset of preprocessor token 
"pp-number". VMD offers functionality for parsing numbers both as a separate element or 
in a sequence of preprocessing tokens. A VMD number is really a subset of VMD identifiers 
for which VMD offers specific functionality. The Boost PP library has it own extensive support
for numbers, which VMD does not duplicate.

VMD v-types are, like numbers, a subset of VMD identifiers consisting of identifiers beginning with
BOOST_VMD_TYPE_ followed by a data type mnemonic. Each v-type can be recognized by VMD functionality
and therefore passed or returned by macros. Like any identifier a v-type can be parsed both as a
separate element or in a sequence of preprocessing tokens.

VMD can also test for emptiness, or the absence of any preprocessing tokens when passed
as macro input.

The Boost PP library supports four individual high-level data types. These are arrays, 
lists, seqs, and tuples. When using variadic macros arrays are really 
obsolete since tuples have all the functionality of arrays with a simpler syntax. 
Nonetheless arrays are fully supported by VMD. A further data type supported by 
Boost PP is variadic data, which is a comma separated grouping of preprocessor elements.
VMD has no special support for variadic data outside of what is already in Boost PP.

VMD has functionality to work with the four Boost PP high-level data types. VMD can 
test the Boost PP data types and parse them in a sequence of preprocessor tokens.

VMD can also parse sequences. A sequence consists of zero or more other top-level
data types already mentioned represented consecutively. As such a sequence represents
any data type which VMD can parse since it can consist of emptiness, a single data type,
or multiple data types represented consecutively.

Emptiness, the three identifier types, the four Boost PP composite data types, and
VMD sequences are the data types which VMD understands. Other low-level preprocessor
data types can of course be used in macro programming but VMD cannot parse such
preprocessor data.

[endsect]