Basic knowledge of C++ is all you need for this recipe. Remember that this library is not a header-only, so your program will need to link against the libboost_program_options library.

Let's start with a simple program that accepts the number of apples and oranges as input and counts the total number of fruits. We want to achieve the following result:

$ our_program –apples=10 –oranges=20
Fruits count: 30

Perform the following steps:

This example is pretty trivial to understand from code and comments. Much more interesting is what output we get on execution:

$ ./our_program --help 
All options: 
  -a [ --apples ] arg (=10) how many apples do you have 
  -o [ --oranges ] arg      how many oranges do you have 
  --name arg                your name 
  --help                    produce help message 

$ ./our_program 
Fruits count: 30

$ ./our_program -a 10 -o 10 --name="Reader" 
Hi,Reader! 
Fruits count: 20

The C++11 standard adopted many Boost libraries; however, you won't find Boost.ProgramOptions in it.

We'll be working with the header-only library. Basic knowledge of C++ is all you need for this recipe.

In such cases, Boost offers a solution, the Boost.Any library, which has an even better syntax:

#include <boost/any.hpp>
#include <iostream>
#include <vector>
#include <string>

int main()
{
    std::vector<boost::any> some_values;
    some_values.push_back(10);
    const char* c_str = "Hello there!";
    some_values.push_back(c_str);
    some_values.push_back(std::string("Wow!"));
    std::string& s = 
       boost::any_cast<std::string&>(some_values.back());
    s += " That is great!\n";
    std::cout << s;
    return 0;
}

Great, isn't it? By the way, it has an empty state, which could be checked using the empty() member function (just as in STL containers).

You can get the value from boost::any using two approaches:

    boost::any variable(std::string("Hello world!"));

    //#1: Following method may throw a boost::bad_any_cast exception
    // if actual value in variable is not a std::string
    std::string s1 = boost::any_cast<std::string>(variable);

    //#2: If actual value in variable is not a std::string
    // will return an NULL pointer
    std::string* s2 = boost::any_cast<std::string>(&variable);

The boost::any class just stores any value in it. To achieve this it uses the type erasure technique (close to what Java or C# does with all of its types). To use this library, you do not really need to know its internal implementation, so let's just have a quick glance at the type erasure technique. Boost.Any, on assignment of some variable of type T, constructs a type (let's call it holder<T>) that may store a value of the specified type T, and is derived from some internal base-type placeholder. A placeholder has virtual functions for getting std::type_info of a stored type and for cloning a stored type. When any_cast<T>() is used, boost::any checks that std::type_info of a stored value is equal to typeid(T) (the overloaded placeholder's function is used for getting std::type_info).

Such flexibility never comes without a cost. Copy constructing, value constructing, copy assigning, and assigning values to instances of boost::any will call a dynamic memory allocation function; all of the type casts need to get runtime type information (RTTI); boost::any uses virtual functions a lot. If you are keen on performance, see the next recipe, which will give you an idea of how to achieve almost the same results without dynamic allocations and RTTI usage.

Another disadvantage of Boost.Any is that it cannot be used with RTTI disabled. There is a possibility to make this library usable even with RTTI disabled, but it is not currently implemented.

We'll be working with the header-only library, which is simple to use. Basic knowledge of C++ is all you need for this recipe.

Let me introduce the Boost.Variant library to you.

The boost::variant class holds an array of characters and stores values in that array. Size of the array is determined at compile time using sizeof() and functions to get alignment. On assignment or construction of boost::variant, the previous values are in-place destroyed, and new values are constructed on top of the character array using the new placement.

The Boost.Variant variables usually do not allocate memory in a heap, and they do not require RTTI to be enabled. Boost.Variant is extremely fast and used widely by other Boost libraries. To achieve maximum performance, make sure that there is a trivial type in the list of supported types, and that this type is at the first position.

Reading the previous two recipes is highly recommended if you are not already familiar with the Boost.Variant and Boost.Any libraries.

The Boost.Variant library implements a visitor programming pattern for accessing the stored data, which is much safer than getting values via boost::get<>. This pattern forces the programmer to take care of each variant type, otherwise the code will fail to compile. You can use this pattern via the boost::apply_visitor function, which takes a visitor functional object as the first parameter and a variant as the second parameter. Visitor functional objects must derive from the boost::static_visitor<T> class, where T is a type being returned by a visitor. A visitor object must have overloads of operator() for each type stored by a variant.

Let's change the cell_t type to boost::variant<int, float, string> and modify our example:

#include <boost/variant.hpp>
#include <vector>
#include <string>
#include <iostream>

// This typedefs and methods will be in header,
// that wraps around native SQL interface.
typedef boost::variant<int, float, std::string> cell_t;
typedef std::vector<cell_t> db_row_t;

// This is just an example, no actual work with database.
db_row_t get_row(const char* /*query*/) {
    // See the recipe "Using a reference to string type" 
    // in Chapter 7, Manipulating Strings
    // for a better type for 'query' parameter.
    db_row_t row;
    row.push_back(10);
    row.push_back(10.1f);
    row.push_back("hello again");
    return row;
}

// This is how code required to sum values
// We can provide no template parameter
// to boost::static_visitor<> if our visitor returns nothing.
struct db_sum_visitor: public boost::static_visitor<double> {
    double operator()(int value) const {
        return value;
    }
    double operator()(float value) const {
        return value;
    }
    double operator()(const std::string& /*value*/) const {
        return 0.0;
    }
};

int main()
{
    db_row_t row = get_row("Query: Give me some row, please.");
    double res = 0.0;
    db_row_t::const_iterator it = row.begin(), end = row.end();
    for (; it != end; ++it) {
         res += boost::apply_visitor(db_sum_visitor(), *it);
    }
    std::cout << "Sum of arithmetic types in database row is: " << res << std::endl;
    return 0;
}

The Boost.Variant library will generate a big switch statement at compile time, each case of which will call a visitor for a single type from the variant's list of types. At runtime, the index of the stored type can be retrieved using which(), and a jump to the correct case in the switch will be made. Something like this will be generated for boost::variant<int, float, std::string>:

switch (which())
{
case 0: return visitor(*reinterpret_cast<int*>(address()));
case 1: return visitor(*reinterpret_cast<float*>(address()));
case 2: return visitor(*reinterpret_cast<std::string*>(address()));
default: assert(false);
}

Here, the address() function returns a pointer to the internal storage of boost::variant<int, float, std::string>.

If we compare this example with the first example in this recipe, we'll see the following advantages of boost::variant:

Only basic knowledge of C++ is required for this recipe.

Ladies and gentlemen, let me introduce you to the Boost.Optional library using the following example:

The try_lock_device() function tries to acquire a lock for a device, and may succeed or not depending on different conditions (in our example it depends on the rand() function call). The function returns an optional variable that can be converted to a Boolean variable. If the returned value is equal to Boolean true, then the lock is acquired, and an instance of a class to work with the device can be obtained by dereferencing the returned optional variable:

#include <boost/optional.hpp>
#include <iostream>
#include <stdlib.h>

class locked_device {
    explicit locked_device(const char* /*param*/) {
        // We have unique access to device
        std::cout << "Device is locked\n";
    }
public:
    ~locked_device () {
        // Releasing device lock
    }

    void use() {
        std::cout << "Success!\n";
    }
    static boost::optional<locked_device> try_lock_device() {
        if (rand()%2) {
            // Failed to lock device
            return boost::none;
        }
        // Success!
        return locked_device("device name");
    }
};

int main()
{
    // Boost has a library called Random. If you wonder why it was 
    // written when stdlib.h has rand() function, see the recipe
    // "Using a true random number generator in Chapter 12, 
    // Scratching the Tip of the Iceberg
    srandom(5);
    for (unsigned i = 0; i < 10; ++i) {
        boost::optional<locked_device> t = locked_device::try_lock_device();
        // optional is convertible to bool
        if (t) {
            t->use();
            return 0;
        } else {
            std::cout << "...trying again\n";
        }
    }
    std::cout << "Failure!\n";
    return -1;
}

This program will output the following:

...trying again 
...trying again 
Device is locked 
Success! 

The Boost.Optional class is very close to the boost::variant class but for only one type, boost::optional<T> has an array of chars, where the object of type T can be an in-place constructor. It also has a Boolean variable to remember the state of the object (is it constructed or not).

The Boost.Optional class does not use dynamic allocation, and it does not require a default constructor for the underlying type. It is fast and considered for inclusion in the next standard of C++. The current boost::optional implementation cannot work with C++11 rvalue references; however, there are some patches proposed to fix that.

The C++11 standard does not include the Boost.Optional class; however, it is currently being reviewed for inclusion in the next C++ standard or in C++14.

Only basic knowledge of C++ is required for this recipe.

We can rewrite the function like this:

#include <boost/array.hpp>
typedef boost::array<char, 4> array4_t;array4_t& vector_advance(array4_t& val);

Here, boost::array<char, 4> is just a simple wrapper around an array of four char elements.

This code answers all of the questions from our first example and is much more readable than the second example.

The first template parameter of boost::array is the element type, and the second one is the size of an array. boost::array is a fixed-size array; if you need to change the array size at runtime, use std::vector or boost::container::vector instead.

The Boost.Array library just contains an array in it. That is all. Simple and efficient. The boost::array<> class has no handwritten constructors and all of its members are public, so the compiler will think of it as a POD type.

Let's see some more examples of the usage of boost::array:

#include <boost/array.hpp>
#include <algorithm>

// Functional object to increment value by one
struct add_1 : public std::unary_function<char, void> {
    void operator()(char& c) const {
        ++ c;
    }
    // If you're not in a mood to write functional objects,
    // but don't know what does 'boost::bind(std::plus<char>(),
    // _1, 1)' do, then read recipe 'Binding a value as a function 
    // parameter'.
};

typedef boost::array<char, 4> array4_t;
array4_t& vector_advance(array4_t& val) {
    // boost::array has begin(), cbegin(), end(), cend(), 
    // rbegin(), size(), empty() and other functions that are 
    // common for STL containers.
    std::for_each(val.begin(), val.end(), add_1());
    return val;
}

int main() {
    // We can initialize boost::array just like an array in C++11:
    // array4_t val = {0, 1, 2, 3};
    // but in C++03 additional pair of curly brackets is required.
    array4_t val = {{0, 1, 2, 3}};

    // boost::array works like a usual array:
    array4_t val_res;       // it can be default constructible and
    val_res = vector_advance(val);  // assignable
    // if value type supports default construction and assignment

    assert(val.size() == 4);
    assert(val[0] == 1);
    /*val[4];*/ // Will trigger an assert because max index is 3
    // We can make this assert work at compile-time.
    // Interested? See recipe 'Checking sizes at compile time' 
    // in Chapter 4, Compile-time Tricks.'
    assert(sizeof(val) == sizeof(char) * array4_t::static_size);
    return 0;
}

One of the biggest advantages of boost::array is that it provides exactly the same performance as a normal C array. People from the C++ standard committee also liked it, so it was accepted to the C++11 standard. There is a chance that your STL library already has it (you may try to include the <array> header and check for the availability of std::array<>).

Only basic knowledge of C++ and STL is required for this recipe.

Perform the following steps to combine multiple values in to one:

Some readers may wonder why we need a tuple when we can always write our own structures with better names, for example, instead of writing boost::tuple<int, std::string>, we can create a structure:

struct id_name_pair {
    int id;
    std::string name;
};

Well, this structure is definitely more clear than boost::tuple<int, std::string>. But what if this structure is used only twice in the code?

The main idea behind the tuple's library is to simplify template programming.

A tuple works as fast as std::pair (it does not allocate memory on a heap and has no virtual functions). The C++ committee found this class to be very useful and it was included in STL; you can find it in a C++11-compatible STL implementation in the header file <tuple> (don't forget to replace all the boost:: namespaces with std::).

The current Boost implementation of a tuple does not use variadic templates; it is just a set of classes generated by a script. There is an experimental version that uses C++11 rvalues and an emulation of them on C++03 compilers, so there is a chance that Boost 1.54 will be shipped with faster implementation of tuples.

Knowledge of C++, STL algorithms, and functional objects is required for this recipe.

Let's take a closer look at the mul_2 function. We provide a vector of values to it, and for each value it applies a functional object returned by the bind() function. The bind() function takes in three parameters; the first parameter is an instance of the std::plus<Number> class (which is a functional object). The second and third parameters are placeholders. The placeholder _1 substitutes the argument with the first input argument of the resulting functional object. As you might guess, there are many placeholders; placeholder _2 means substituting the argument with the second input argument of the resulting functional object, and the same also applies to placeholder _3. Well, seems you've got the idea.

Just to make sure that you've got the whole idea and know where bind can be used, let's take a look at another example.

We have two classes, which work with some sensor devices. The devices and classes are from different vendors, so they provide different APIs. Both classes have only one public method watch, which accepts a functional object:

class Device1 {
private:
    short temperature();
    short wetness();
    int illumination();
    int atmospheric_pressure();
    void wait_for_data();
public:
    template <class FuncT>
    void watch(const FuncT& f) {
        for(;;) {
            wait_for_data();
            f(
                temperature(),
                wetness(),
                illumination(),
                atmospheric_pressure()
            );
        }
    }
};

class Device2 {
private:
    short temperature();
    short wetness();
    int illumination();
    int atmospheric_pressure();
    void wait_for_data();
public:
    template <class FuncT>
    void watch(const FuncT& f) {
        for(;;) {
            wait_for_data();
            f(
                wetness(),
                temperature(),
                atmospheric_pressure(),
                illumination()
            );
        }
    }
};

The Device1::watch and Device2::watch functions pass values to a functional object in a different order.

Some other libraries provide a function, which is used to detect storms, and throws an exception when the risk of a storm is high enough:

void detect_storm(int wetness, int temperature, int atmospheric_pressure);

Your task is to provide a storm-detecting function to both of the devices. Here is how it can be achieved using the bind function:

    Device1 d1;
    // resulting functional object will silently ignore 
    // additional parameters passed to function call
    d1.watch(boost::bind(&detect_storm, _2, _1, _4));
    ...
    Device2 d2;
    d2.watch(boost::bind(&detect_storm, _1, _2, _3));

The Boost.Bind library provides good performance because it does not use dynamic allocations and virtual functions. It is useful even when the C++11 lambda functions are not usable:

template <class FuncT>
void watch(const FuncT& f) {
    f(10, std::string("String"));
    f(10, "Char array");
    f(10, 10);
}

struct templated_foo {
    template <class T>
    void operator()(T, int) const {
        // No implementation, just showing that bound
        // functions still can be used as templated
    }
};

void check_templated_bind() {
    // We can directly specify return type of a functional object
    // when bind fails to do so
    watch(boost::bind<void>(templated_foo(), _2, _1));
}

Bind is a part of the C++11 standard. It is defined in the <functional> header and may slightly differ from the Boost.Bind implementation (however, it will be at least as effective as Boost's implementation).

Read the previous recipe to get an idea of placeholders, or just make sure that you are familiar with C++11 placeholders. Knowledge of STL functions and algorithms is welcomed.

Let's see some examples of the usage of Boost.Bind along with traditional STL classes:

The boost::bind function returns a functional object that stores a copy of the bound values and a copy of the original functional object. When the actual call to operator() is performed, the stored parameters are passed to the original functional object along with the parameters passed at the time of call.

Take a look at the previous examples. When we are binding values, we copy a value into a functional object. For some classes this operation is expensive. Is there a way to bypass copying?

Yes, there is! And the Boost.Ref library will help us here! It contains two functions, boost::ref() and boost::cref(), the first of which allows us to pass a parameter as a reference, and the second one passes the parameter as a constant reference. The ref() and cref() functions just construct an object of type reference_wrapper<T> or reference_wrapper<const T>, which is implicitly convertible to a reference type. Let's change our previous examples:

#include <boost/ref.hpp>
...
std::string s("Expensive copy constructor of std::string now "
             "won't be called when binding");
count0 = std::count_if(str_values.begin(), str_values.end(), std::bind2nd(std::less<std::string>(), boost::cref(s)));
count1 = std::count_if(str_values.begin(), str_values.end(), boost::bind(std::less<std::string>(), _1, boost::cref(s)));
assert(count0 == count1);

Just one more example to show you how boost::ref can be used to concatenate strings:

void wierd_appender(std::string& to, const std::string& from) {
    to += from;
};

std::string result;
std::for_each(str_values.cbegin(), str_values.cend(), boost::bind(&wierd_appender, boost::ref(result), _1));
assert(result == "We are the champions!");

The functions ref and cref (and bind) are accepted to the C++11 standard and defined in the <functional> header in the std:: namespace. None of these functions dynamically allocate memory in the heap and they do not use virtual functions. The objects returned by them are easy to optimize and they do not apply any optimization barriers for good compilers.

STL implementations of those functions may have additional optimizations to reduce compilation time or just compiler-specific optimizations, but unfortunately, some STL implementations miss the functionality of Boost versions. You may use the STL version of those functions with any Boost library, or even mix Boost and STL versions.

It is highly recommended to at least know the basics of C++11 rvalue references.

Now, let's take a look at the following examples:

Here is an example of how the move assignment can be used:

    person_info vasya;
    vasya.name_ = "Vasya";
    vasya.second_name_ = "Snow";
    vasya.is_male_ = true;

    person_info new_vasya(boost::move(vasya));
    assert(new_vasya.name_ == "Vasya");
    assert(new_vasya.second_name_ == "Snow");
    assert(vasya.name_.empty());
    assert(vasya.second_name_.empty());

    vasya = boost::move(new_vasya);
    assert(vasya.name_ == "Vasya");
    assert(vasya.second_name_ == "Snow");
    assert(new_vasya.name_.empty());
    assert(new_vasya.second_name_.empty());

The Boost.Move library is implemented in a very efficient way. When the C++11 compiler is used, all the macros for rvalues emulation will be expanded to C++11-specific features, otherwise (on C++03 compilers) rvalues will be emulated using specific datatypes and functions that never copy passed values nor called any dynamic memory allocations or virtual functions.

Have you noticed the boost::swap call? It is a really helpful utility function, which will first search for a swap function in the namespace of a variable (the namespace other::), and if there is no swap function for the characteristics class, it will use the STL implementation of swap.

Only very basic knowledge of C++ is required for this recipe.

To avoid such situations, the boost::noncopyable class was invented. If you derive your own class from it, the copy constructor and assignment operator won't be generated by the C++ compiler:

#include <boost/noncopyable.hpp>

class descriptor_owner_fixed : private boost::noncopyable {
    …

Now the user won't be able to do bad things:

    descriptor_owner_fixed d1("O_o");
    descriptor_owner_fixed d2("^_^");
    // Won't compile
    d2 = d1;
    // Won't compile either
    descriptor_owner_fixed d3(d1);

A sophisticated reader will tell me that we can achieve exactly the same result by making a copy constructor and an assignment operator of descriptor_owning_fixed private, or just by defining them without actual implementation. Yes, you are correct. Moreover, this is the current implementation of the boost::noncopyable class. But boost::noncopyable also serves as good documentation for your class. It never raises questions such as "Is the copy constructor body defined elsewhere?" or "Does it have a nonstandard copy constructor (with a nonconst referenced parameter)?".

It is highly recommended to know at least the basics of C++11 rvalue references. Reading the Using the C++11 move emulation recipe is also recommended.

Those readers who use C++11 already know about the move-only classes (like std::unique_ptr or std::thread). Using such an approach, we can make a move-only descriptor_owner class:

class descriptor_owner1 {
    void* descriptor_;

public:
    descriptor_owner1()
        : descriptor_(NULL)
    {}

    explicit descriptor_owner1(const char* param)
        : descriptor_(strdup(param))
    {}

    descriptor_owner1(descriptor_owner1&& param)
        : descriptor_(param.descriptor_)
    {
        param.descriptor_ = NULL;
    }

    descriptor_owner1& operator=(descriptor_owner1&& param) {
        clear();
        std::swap(descriptor_, param.descriptor_);
        return *this;
    }

    void clear() {
        free(descriptor_);
        descriptor_ = NULL;
    }

    bool empty() const {
        return !descriptor_;
    }

    ~descriptor_owner1() {
        clear();
    }
};

// GCC compiles the following in with -std=c++0x
descriptor_owner1 construct_descriptor2() {
    return descriptor_owner1("Construct using this string");
}

void foo_rv() {
    std::cout << "C++11\n";
    descriptor_owner1 desc;
    desc = construct_descriptor2();
    assert(!desc.empty());
}

This will work only on C++11 compatible compilers. That is the right moment for Boost.Move! Let's modify our example so it can be used on C++03 compilers.

According to the documentation, to write a movable but noncopyable type in portable syntax, we need to follow these simple steps:

Now we have a movable but noncopyable class that can be used even on C++03 compilers and in Boost.Containers:

#include <boost/container/vector.hpp>
...
    // Following code will work on C++11 and C++03 compilers
    descriptor_owner_movable movable;
    movable = construct_descriptor3();
    boost::container::vector<descriptor_owner_movable> vec;
    vec.resize(10);
    vec.push_back(construct_descriptor3());

    vec.back() = boost::move(vec.front());

But unfortunately, C++03 STL containers still won't be able to use it (that is why we used a vector from Boost.Containers in the previous example).

If you want to use Boost.Containers on C++03 compilers and STL containers, on C++11 compilers you can use the following simple trick. Add the header file to your project with the following content:

// your_project/vector.hpp
// Copyright and other stuff goes here

// include guards
#ifndef YOUR_PROJECT_VECTOR_HPP
#define YOUR_PROJECT_VECTOR_HPP

#include <boost/config.hpp>

// Those macro declared in boost/config.hpp header
// This is portable and can be used with any version of boost 
// libraries
#if !defined(BOOST_NO_RVALUE_REFERENCES) && !defined(BOOST_NO_CXX11_RVALUE_REFERENCES)
// We do have rvalues
#include <vector>

namespace your_project_namespace {
  using std::vector;
} // your_project_namespace

#else
// We do NOT have rvalues
#include <boost/container/vector.hpp>

namespace your_project_namespace {
  using boost::container::vector;
} // your_project_namespace

#endif // !defined(BOOST_NO_RVALUE_REFERENCES) && !defined(BOOST_NO_CXX11_RVALUE_REFERENCES)
#endif // YOUR_PROJECT_VECTOR_HPP

Now you can include <your_project/vector.hpp> and use a vector from the namespace your_project_namespace:

    your_project_namespace::vector<descriptor_owner_movable> v;
    v.resize(10);
    v.push_back(construct_descriptor3());
    v.back() = boost::move(v.front());

But beware of compiler- and STL-implementation-specific issues! For example, this code will compile on GCC 4.7 in C++11 mode only if you mark the move constructor, destructor, and move assignment operators with noexcept.