The Cxx Dual library, or CXXD for short, is a macro library which chooses between using a Boost library or its C++ standard equivalent library for a number of different C++ implementations, while allowing the end-user to use the same code to program either choice. An implementation is a Boost library which has a C++ standard library equivalent whose public interfaces are nearly the same in both cases. An 'implementation' is called a 'mod' for short and each of the possible Boost or C++ standard implementations for that mod are called a 'dual library'.

The library does this by:

All of this is done on a per-mod basis when a header file representing that mod is included by the end-user in his code. Any single mod is completely separated from all other mods, so that the use of each mod is self-contained and does not involve the use of anything else in the CXXD library.

The CXXD library also provides:

Basic example using CXXD

Let us say that the end-user wishes to use the C++ regex mod functionality in his code in order to create a regular expression object and use it to find data in a string based on that regular expression.

If the end-user had chosen to use the Boost regex library his code could be:

#include <boost/regex.hpp>

void SomeFunction()
    {
    boost::regex re("A regular expression etc.");
    bool result(boost::regex_match("Some string...",re));
    // etc.
    }

If the end-user had chosen to use the C++ standard library his code could be:

#include <regex>

void SomeFunction()
    {
    std:regex re("A regular expression etc.");
    bool result(std::regex_match("Some string...",re));
    // etc.
    }

However the end-user's goal is that if the C++ standard library regex implementation is available he wants to use that, otherwise he wants to use the Boost regex implementation. Most importantly he wants to use the exact same code to achieve his goals no matter which implementation he uses. To do that he uses CXXD. Using CXXD we use the regex mod and we could code:

#include <boost/cxx_dual/regex.hpp>

void SomeFunction()
    {
    cxxd_regex_ns::regex re("A regular expression etc.");
    bool result(cxxd_regex_ns::regex_match("Some string...",re));
    // etc.
    }

The header file representing the regex mod is included. This includes whatever header files are needed by the regex library chosen. Afterwards regex namespace alias is used to program with whichever regex dual library is chosen.

This is all one has to do to use the CXXD library in its most basic mode. Despite the fact that CXXD is a macro library, and many programmers are distrustful and afraid to use macros, the vast majority of actual user code when using CXXD does not use CXXD macros at all.

CXXD mods

There are currently 28 different mods in CXXD and each mod has its own header file to be included in order to use that mod in your code, and each has its own namespace alias to be used.

This basic use of CXXD is very simple, yet it provides the ability to program using any of the 28 different mods supported in a way such that the choice of which dual library is actually used for a particular mod is automatically made by CXXD.

Who the library is for

The CXXD library is for any programmer who wants to let CXXD decide whether to use the C++ standard library or the Boost library version of a mod at compile time, and who wants to write a single set of code for either library.

On a more practical basis the CXXD library is for:

Current CXXD alternatives

Popular alternative choices in programmers's code are:

The first choice is easily the most popular since Boost library developers, and those involved using any one of the approximately current 130+ Boost libraries, assume that a Boost distribution is always available for the programmer to use. What are the possible negatives in the first choice ?

The second choice, always using the C++ standard equivalent library, will occur less often because of its most obvious negative; if the C++ standard library is not available for a particular compiler implementation and C++ standard compiler level, the code will fail to compile. If however you write a library for a particular level of the C++ standard, such as C++11, and assume a strong implementation of that standard is needed by certain compilers which can compile your code, this is often your most viable choice.

The third choice, supporting both the Boost version of a library and the equivalent C++ standard version of that library, is obviously programmable but entails a much greater amount of work. Each usage of a mod will entail writing code that supports both libraries and this will require a great deal of extra code. Furthermore your code will be filled with uses of preprocessor #if statements to delineate which usage of a mod would be available at any given time.

All these choices are understandable. The CXXD library offers another choice and the purpose of the library is to provide that other choice to programmers who see it as a viable one.

CXXD basic mode

Using CXXD in its basic mode has been briefly illustrated above. There are more areas of basic mode that will be explored, though those areas are more rarely used. But before I go on to explore those areas, and to list the mods supported by CXXD, I want to give some terminology that will be used in this documentation in the next section.