How the value stored in a variant is consumed usually depends on the type of the value. Checking a variant for each possible type using an if-else ladder can quickly aggravate the readability and maintainability of your code. Of course, we can find out the zero-based index of the type of the current value using the which member method of the variant, but it would be of little immediate use. Instead, we will look at a very elegant and versatile compile-time visitation mechanism provided by the Boost Variant library without which handling variants would be quite a drag.

The idea is to create a visitor class that contains an overloaded function call operator (operator()) to handle each type that may be stored in the variant. Using the function boost::apply_visitor, we can invoke the appropriate overload in the visitor class on a variant object, based on the type of value it contains.

The visitor class should publicly inherit from the boost::static_visitor<T> template, where T is the return type of the overloaded function call operator. By default, T is void. Let us look at an example:

Listing 2.6: Compile-time visitation of variants

 1 #include <boost/variant.hpp>
 2 
 3 struct SimpleVariantVisitor :public boost::static_visitor<void>
 4 {
 5   void operator() (const std::string& s) const
 6   { std::cout << "String: " << s << '\n'; }
 7 
 8   void operator() (long n) const
 9   { std::cout << "long: " << n << '\n'; }
10 };
11 
12 int main()
13 {
14   boost::variant<std::string, long, double> v1;
15   v1 = 993.3773;
16 
17   boost::apply_visitor(SimpleVariantVisitor(), v1);
18 }

We create a variant over the types std::string, long, and double called v1 (line 14). We set it to a value of type double (line 15). Finally, we invoke a visitor of type SimpleVariantVistor on v1 (line 17). The SimpleVariantVisitor inherits from boost::apply_visitor<void> (line 3) and contains overloads of operator() for std::string (line 5) and long (line 8) but not double. Each overload prints its argument to the standard output.

The resolution of overloads happens at compile time rather than at runtime. Thus, an overload must be available for every type of value that the variant may contain. A particular overload is invoked if its parameter type is the best match for the type of the value stored in the variant. Moreover, a single overload may handle multiple types if all the types are convertible to the type of the argument of the overload.

Interestingly, in the preceding example, there is no overload available for double. However, narrowing conversions are allowed and the overload for long is invoked with potential narrowing. In this case, the overload for long handles both long and double types. On the other hand, if we had separate overloads available for double and long but none for std::string, we would have had a compilation error. This would happen because not even a narrowing conversion would be available from std::string to either long or double, and the overload resolution would fail. Being a compile-time mechanism, this is independent of the type of the actual value stored in a variant object at any time.

You may create a member function template that handles a family of types. In cases where the code for handling different types does not significantly differ, it may make sense to have such member templates. Here is an example of a visitor which prints the contents of the variant:

Listing 2.7: Generic compile-time visitation

 1 #include <boost/variant.hpp>
 2
 3 struct PrintVisitor : boost::static_visitor<>
 4 {
 5    template <typename T>
 6    void operator() (const T& t) const {
 7      std::cout << t << '\n';
 8    }
 9 };
10
11 boost::variant<std::string, double, long, Foo> v1;
12 boost::apply_visitor(PrintVisitor(), v1);

In the preceding code, we define a variant over the types std::string, double, long, and Foo. The visitor class PrintVisitor contains a generic operator(). As long as all the types in the variant are streamable, this code will compile and print the value of the variant to the standard output.

Often, we have an STL container of variant objects, and we want to visit each object using our visitor. We can utilize the std::for_each STL algorithm and a single-argument overload of boost::apply_visitor for the purpose. The single-argument overload of boost::apply_visitor takes a visitor instance and returns a functor that applies the visitor to a passed element. The following example best illustrates the usage:

 1 #include <boost/variant.hpp>
 2
 3 std::vector<boost::variant<std::string, double, long> > vvec;
 4 …
 5 std::for_each(vvec.begin(), vvec.end(),
 6                  boost::apply_visitor(SimpleVariantVisitor()));

To start with, we will look at an example of people records in the JSON notation:

    {
        "Name": "Lucas",
        "Age": 38,
        "PhoneNumbers" : ["1123654798", "3121548967"],
        "Address" : { "Street": "27 Riverdale", "City": "Newtown", 
                             "PostCode": "902739"}
    }

The preceding code is an example of a JSON object—it contains key-value pairs identifying the attributes of an unnamed object. The attribute names are quoted strings, such as "Name", "Age", "PhoneNumbers" (of which you can have more than one), and "Address". Their values could be simple strings ("Name") or numeric values ("Age"), or arrays of such values ("PhoneNumbers") or other objects ("Address"). A single colon (:) separates keys from values. The key-value pairs are separated by commas. The list of key-value pairs in an object are enclosed in curly braces. This format allows arbitrary levels of nesting as seen in the case of the "Address" attribute whose value itself is an object. You can create more nested objects that are values of attributes of other nested objects.

You may combine many such records together in an array, which are enclosed in square brackets and separated by commas:

[
    {
        "Name": "Lucas",
        "Age": 38,
        "PhoneNumbers" : ["1123654798", "3121548967"],
        "Address" : { "Street": "27 Riverdale", "City": "Newtown", 
                             "PostCode": "902739"}
    },
    {
        "Name": "Damien",
        "Age": 52,
        "PhoneNumbers" : ["6427851391", "3927151648"],
        "Address": {"Street": "11 North Ave.", "City" : "Rockport", 
                        "PostCode": "389203"}
    },
    … 
]

A well-formed JSON text contains an object or an array of zero or more objects, numeric values, strings, Booleans, or null values. An object itself contains zero or more unique attributes each represented by a unique string. The value of each attribute can be a string, numeric value, Boolean value, null value, another object, or an array of such values. Thus, the basic tokens in JSON content are numeric values, strings, Booleans, and nulls. The aggregates are objects and arrays.

If we were to declare a variant to represent a basic token in a JSON, it would look like this:

 1 struct JSONNullType {};
 2 boost::variant<std::string, double, bool, JSONNullType> jsonToken;

The type JSONNullType is an empty type that may be used to represent a null element in JSON.

To extend this variant to represent more complex JSON content, we will try to represent a JSON object—a key-value pair as a type. The keys are always strings, but the values can be any of the types listed above or another nested object. So, the definition of a JSON object is essentially recursive, and this is why we need a recursive variant definition to model it.

To include the definition of a JSON object in the preceding variant type, we use a metafunction called boost::make_recursive_variant. It takes a list of types and defines the resultant recursive variant type as a nested type called type. So, here is how we write a recursive definition of the variant:

 1 #define BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT
 2 #include <boost/variant.hpp>
 3
 4 struct JSONNullType {};
 5
 6 typedef boost::make_recursive_variant<
 7                      std::string,
 8                      double,
 9                      bool,
10                      JSONNullType,
11                      std::map<std::string,
12                               boost::recursive_variant_>
13                     >::type JSONValue;

The #define statement on line 1 may be necessary for many compilers where the support for recursive variants, especially using make_recursive_variant, is limited.

We define the recursive variant using the boost::make_recursive_variant metafunction (line 6). In the list of types, we add a new type std::map with keys of type std::string (line 11) and values of type boost::recursive_variant_ (line 12). The special type boost::recursive_variant_ is used to indicate that the outer variant type can occur as a value in the map itself. Thus, we have captured the recursive nature of a JSON object in the variant definition.

This definition is still not complete. A well-formed JSON content may contain arrays of elements of all these different kinds. Such arrays may also be the values of an object's attributes or be nested inside other arrays. If we choose to represent an array by a vector, then an extension of the preceding definition is easy:

Listing 2.8a: Recursive variant for JSON

 1 #define BOOST_VARIANT_NO_FULL_RECURSIVE_VARIANT_SUPPORT
 2 #include <boost/variant.hpp>
 3
 4 struct JSONNullType {};
 5
 6 typedef boost::make_recursive_variant<
 7                      std::string,
 8                      double,
 9                      bool,
10                      JSONNullType,
11                      std::map<std::string,
12                               boost::recursive_variant_>,
13                      std::vector<boost::recursive_variant_>
14                     >::type JSONValue;
15
16 typedef std::vector<JSONValue> JSONArray;
17 typedef std::map<std::string, JSONValue> JSONObject;

We add one more type—std::vector<boost::recursive_variant_> (line 13)—which represents an array of JSONValue objects. By virtue of this one additional line, we now support several more possibilities:

This is the complete definition of JSONValue. In addition, we create typedefs for the recursive aggregate types—JSON arrays and JSON objects (line 16 and 17).

We shall now write a visitor to print JSON data stored in a variant in its standard notation. Visiting a recursive variant is not different from visiting a nonrecursive one. We still need to define overloads that can handle all types of values that the variant may store. In addition, in the overloads for the recursive aggregate types (in this case, JSONArray and JSONObject), we may need to recursively visit each of its elements:

Listing 2.8b: Visiting recursive variants

 1 void printArrElem(const JSONValue& val);
 2 void printObjAttr(const JSONObject::value_type& val); 
 3
 4 struct JSONPrintVisitor : public boost::static_visitor<void>
 5 {
 6   void operator() (const std::string& str) const
 7   {
 8     std::cout << '"' << escapeStr(str) << '"';
 9   }
10
11   void operator() (const JSONNullType&) const
12   {
13     std::cout << "null";
14   }
15
16   template <typename T>
17   void operator()(const T& value) const
18   {
19     std::cout << std::boolalpha << value;
20   }
21
22   void operator()(const JSONArray& arr) const
23   {
24     std::cout << '[';
25
26     if (!arr.empty()) {
27       boost::apply_visitor(*this, arr[0]);
28       std::for_each(arr.begin() + 1, arr.end(), printArrElem);
29     }
30 
31     std::cout << "\n";
32   }
33
34   void operator()(const JSONObject& object) const
35   {
36     std::cout << '{';
37 
38     if (!object.empty()) {
39       const auto& kv_pair = *(object.begin());
40       std::cout << '"' << escapeStr(kv_pair.first) << '"';
41       std::cout << ':';
42       boost::apply_visitor(*this, kv_pair.second);
43
44       auto it = object.begin();
45       std::for_each(++it, object.end(), printObjAttr);
46     }
47     std::cout << '}';
48   }
49
50 };
51
52 void printArrElem(const JSONValue& val) {
53   std::cout << ',';
54   boost::apply_visitor(JSONPrintVisitor(), val);
55 }
56
57 void printObjAttr(const JSONObject::value_type& val) {
58   std::cout << ',';
59   std::cout << '"' << escapeStr(val.first) << '"';
60   std::cout << ':';
61   boost::apply_visitor(JSONPrintVisitor(), val.second);
62 }

The visitor JSONPrintVisitor inherits publicly from boost::static_visitor<void> and provides overloads of operator() for the different possible types of JSON values. There is an overload for std::string (line 6), which prints strings in double quotes (line 8) after escaping any embedded quotes and other characters that need escaping. For this, we assume the availability of a function called escapeStr. We have a second overload for the JSONNullType (line 11), which just prints the string null without quotes. Other types of values, such as double or bool are handled by the member template (line 17). For bool values, it prints the unquoted strings true and false using the std::boolalpha ostream manipulator (line 19).

The main work is done by the two overloads for JSONArray (line 22) and JSONObject (line 34). The JSONArray overload prints the elements of the array enclosed in square brackets and separated by commas. It prints the first element of the vector of JSONValues (line 27) and then, applies the std::for_each generic algorithm on this vector, starting with its second element to print the subsequent elements separated by commas (line 28). For this purpose, it passes as the third argument to std::for_each, a pointer to the function printArrElem. The printArrElem (line 52) function prints each element by applying JSONPrintVisitor (line 54).

The JSONObject overload prints the elements of the map as a comma-separated list of key-value pairs. The first pair is printed as a quoted, escaped key (line 40), then a colon (line 41) followed by a call to boost::apply_visitor (line 42). Subsequent pairs are printed separated by commas from the preceding ones by iterating over the remaining elements of the map using the std::for_each and printObjAttr function pointers (line 45). The logic is analogous to that in the JSONArray overload. The printObjAttr function (line 57) prints each key-value pair passed to it, prefixing a comma (line 58), printing the escaped, quoted key (line 59), prints a colon (line 60), and invoking the visitor on the variant value (line 61).