Kevlin
Henney
2001
Kevlin Henney
2013-2022
Antony Polukhin
Safe, generic container for single values of different value types

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)

# Boost.Any

# Introduction

There are times when a generic (in the sense of general as opposed to template-based programming) type is needed: variables that are truly variable, accommodating values of many other more specific types rather than C++'s normal strict and static types. We can distinguish three basic kinds of generic type:

- Converting types that can hold one of a number of possible value types, e.g. `int` and `string`, and freely convert between them, for instance interpreting `5` as `"5"` or vice-versa. Such types are common in scripting and other interpreted languages. `boost::lexical_cast` supports such conversion functionality.

- Discriminated types that contain values of different types but do not attempt conversion between them, i.e. `5` is held strictly as an `int` and is not implicitly convertible either to `"5"` or to `5.0`. Their indifference to interpretation but awareness of type effectively makes them safe, generic containers of single values, with no scope for surprises from ambiguous conversions.

- Indiscriminate types that can refer to anything but are oblivious to the actual underlying type, entrusting all forms of access and interpretation to the programmer. This niche is dominated by `void *`, which offers plenty of scope for surprising, undefined behavior.

The ``boost::any`` class (based on the class of the same name described in "Valued Conversions" by Kevlin Henney, C++ Report 12(7), July/August 2000) is a variant value type based on the second category. It supports copying of any value type and safe checked extraction of that value strictly against its type. A similar design, offering more appropriate operators, can be used for a generalized function adaptor, `any_function`, a generalized iterator adaptor, `any_iterator`, and other object types that need uniform runtime treatment but support only compile-time template parameter conformance.

# Examples

The following code demonstrates the syntax for using implicit conversions to and copying of any objects:

    #include <list>
    #include <boost/any.hpp>

    using boost::any_cast;
    typedef std::list<boost::any> many;

    void append_int(many & values, int value)
    {
        boost::any to_append = value;
        values.push_back(to_append);
    }

    void append_string(many & values, const std::string & value)
    {
        values.push_back(value);
    }

    void append_char_ptr(many & values, const char * value)
    {
        values.push_back(value);
    }

    void append_any(many & values, const boost::any & value)
    {
        values.push_back(value);
    }

    void append_nothing(many & values)
    {
        values.push_back(boost::any());
    }

The following predicates follow on from the previous definitions and demonstrate the use of queries on any objects:

    bool is_empty(const boost::any & operand)
    {
        return operand.empty();
    }

    bool is_int(const boost::any & operand)
    {
        return operand.type() == typeid(int);
    }

    bool is_char_ptr(const boost::any & operand)
    {
        try
        {
            any_cast<const char *>(operand);
            return true;
        }
        catch(const boost::bad_any_cast &)
        {
            return false;
        }
    }

    bool is_string(const boost::any & operand)
    {
        return any_cast<std::string>(&operand);
    }

    void count_all(many & values, std::ostream & out)
    {
        out << "#empty == "
            << std::count_if(values.begin(), values.end(), is_empty) << std::endl;
        out << "#int == "
            << std::count_if(values.begin(), values.end(), is_int) << std::endl;
        out << "#const char * == "
            << std::count_if(values.begin(), values.end(), is_char_ptr) << std::endl;
        out << "#string == "
            << std::count_if(values.begin(), values.end(), is_string) << std::endl;
    }

The following type, patterned after the OMG's Property Service, defines name-value pairs for arbitrary value types:

    struct property
    {
        property();
        property(const std::string &, const boost::any &);

        std::string name;
        boost::any value;
    };

    typedef std::list<property> properties;

The following base class demonstrates one approach to runtime polymorphism based callbacks that also require arbitrary argument types. The absence of virtual member templates requires that different solutions have different trade-offs in terms of efficiency, safety, and generality. Using a checked variant type offers one approach:

    class consumer
    {
    public:
        virtual void notify(const any &) = 0;
        ...
    };

# ValueType requirements

Values are strongly informational objects for which identity is not significant, i.e. the focus is principally on their state content and any behavior organized around that. Another distinguishing feature of values is their granularity: normally fine-grained objects representing simple concepts in the system such as quantities.

As the emphasis of a value lies in its state not its identity, values can be copied and typically assigned one to another, requiring the explicit or implicit definition of a public copy constructor and public assignment operator. Values typically live within other scopes, i.e. within objects or blocks, rather than on the heap. Values are therefore normally passed around and manipulated directly as variables or through references, but not as pointers that emphasize identity and indirection.

The specific requirements on value types to be used in an ``boost::any`` and ``boost::anys::basic_any`` are:

- A ValueType is CopyConstructible [20.1.3].

- The destructor for a ValueType upholds the no-throw exception-safety guarantee.

A class whose instances can hold instances of any type that satisfies ValueType requirements.

`this->`empty`()`

const `any` &

Copy constructor that copies content of `other` into new instance, so that any content is equivalent in both type and value to the content of `other`, or empty if `other` is empty.

May fail with a ``std::bad_alloc`` exception or any exceptions arising from the copy constructor of the contained type.

any
&&

Move constructor that moves content of `other` into new instance and leaves `other` empty.

C++11 compatible compiler.

`other->`empty`()`

Nothing.

const ValueType &

Makes a copy of `value`, so that the initial content of the new instance is equivalent in both type and value to `value`.

``std::bad_alloc`` or any exceptions arising from the copy constructor of the contained type.

ValueType &&

Forwards `value`, so that the initial content of the new instance is equivalent in both type and value to `value` before the forward.

C++11 compatible compiler.

``std::bad_alloc`` or any exceptions arising from the move or copy constructor of the contained type.

Releases any and all resources used in management of instance.

Nothing.

`any` &

const `any` &

Copies content of `rhs` into current instance, discarding previous content, so that the new content is equivalent in both type and value to the content of `rhs`, or empty if `rhs.`empty`()`.

``std::bad_alloc`` or any exceptions arising from the copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

`any` &

any
&&

Moves content of `rhs` into current instance, discarding previous content, so that the new content is equivalent in both type and value to the content of `rhs` before move, or empty if `rhs.`empty`()`.

C++11 compatible compiler.

`rhs->`empty`()`

Nothing.

`any` &

const ValueType &

Makes a copy of `rhs`, discarding previous content, so that the new content of is equivalent in both type and value to `rhs`.

``std::bad_alloc`` or any exceptions arising from the copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

`any` &

ValueType &&

Forwards `rhs`, discarding previous content, so that the new content of is equivalent in both type and value to `rhs` before forward.

C++11 compatible compiler.

``std::bad_alloc`` or any exceptions arising from the move or copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

`any` &

any
&

Exchange of the contents of `*this` and `rhs`.

`*this`

Nothing.

bool

`true` if instance is empty, otherwise `false`.

Nothing.

const `std::type_info` &

the `typeid` of the contained value if instance is non-empty, otherwise `typeid(void)`.

Useful for querying against types known either at compile time or only at runtime.

void ``any` &` ``any` &`

Exchange of the contents of `lhs` and `rhs`.

Nothing.

T

any
&
T

any
&&
T

const `any` &
const ValueType *

const `any` *
ValueType *

any
*

Custom keyword cast for extracting a value of a given type from an ``any``.

If passed a pointer, it returns a similarly qualified pointer to the value content if successful, otherwise null is returned. If T is ValueType, it returns a copy of the held value, otherwise, if T is a reference to (possibly const qualified) ValueType, it returns a reference to the held value.

Overloads taking an ``any`` pointer do not throw; overloads taking an ``any`` value or reference throws ``bad_any_cast`` if unsuccessful.

std::bad_cast
The exception thrown in the event of a failed `any_cast` of an ``any`` value.
const char *
A class with customizable Small Object Optimization whose instances can hold instances of any type that satisfies ValueType requirements. Use ``boost::any`` instead if not sure.

``boost::anys::basic_any`` is the drop-in replacement for ``boost::any`` that provides controll over Small Object Optimization via `OptimizeForSize` and `OptimizeForAlignment` template parameters.

There are certain applications that require ``boost::any`` functionality, do know the typical/maximal size of the stored object and wish to avoid dynamic memory allocation overhead. For the convenience such applications may create a typedef for `basic_any` with the `OptimizeForSize` and `OptimizeForAlignment` template parameters set to typical/maximal size and alignment of types respectively. Memory allocation would be avoided for storing nothrow move constructible types with size and alignment less than or equal to the `OptimizeForSize` and `OptimizeForAlignment` values.

Otherwise just use ``boost::any``.

std::size_t
std::size_t

`this->`empty`()`

const `basic_any` &

Copy constructor that copies content of `other` into new instance, so that any content is equivalent in both type and value to the content of `other`, or empty if `other` is empty.

May fail with a ``std::bad_alloc`` exception or any exceptions arising from the copy constructor of the contained type.

basic_any
&&

Move constructor that moves content of `other` into new instance and leaves `other` empty.

C++11 compatible compiler.

`other->`empty`()`

Nothing.

const ValueType &

Makes a copy of `value`, so that the initial content of the new instance is equivalent in both type and value to `value`.

Does not dynamically allocate if `ValueType` is nothrow move constructible and `sizeof(value) <= OptimizeForSize && alignof(value) <=OptimizeForAlignment`.

``std::bad_alloc`` or any exceptions arising from the copy constructor of the contained type.

ValueType &&

Forwards `value`, so that the initial content of the new instance is equivalent in both type and value to `value` before the forward.

Does not dynamically allocate if `ValueType` is nothrow move constructible and `sizeof(value) <= OptimizeForSize && alignof(value) <=OptimizeForAlignment`.

C++11 compatible compiler.

``std::bad_alloc`` or any exceptions arising from the move or copy constructor of the contained type.

Releases any and all resources used in management of instance.

Nothing.

`basic_any` &

const `basic_any` &

Copies content of `rhs` into current instance, discarding previous content, so that the new content is equivalent in both type and value to the content of `rhs`, or empty if `rhs.`empty`()`.

``std::bad_alloc`` or any exceptions arising from the copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

`basic_any` &

basic_any
&&

Moves content of `rhs` into current instance, discarding previous content, so that the new content is equivalent in both type and value to the content of `rhs` before move, or empty if `rhs.`empty`()`.

C++11 compatible compiler.

`rhs->`empty`()`

Nothing.

`basic_any` &

const ValueType &

Makes a copy of `rhs`, discarding previous content, so that the new content of is equivalent in both type and value to `rhs`.

Does not dynamically allocate if `ValueType` is nothrow move constructible and `sizeof(value) <= OptimizeForSize && alignof(value) <=OptimizeForAlignment`.

``std::bad_alloc`` or any exceptions arising from the copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

`basic_any` &

ValueType &&

Forwards `rhs`, discarding previous content, so that the new content of is equivalent in both type and value to `rhs` before forward.

Does not dynamically allocate if `ValueType` is nothrow move constructible and `sizeof(value) <= OptimizeForSize && alignof(value) <=OptimizeForAlignment`.

C++11 compatible compiler.

``std::bad_alloc`` or any exceptions arising from the move or copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

`basic_any` &

basic_any
&

Exchange of the contents of `*this` and `rhs`.

`*this`

Nothing.

bool

`true` if instance is empty, otherwise `false`.

Nothing.

const `std::type_info` &

the `typeid` of the contained value if instance is non-empty, otherwise `typeid(void)`.

Useful for querying against types known either at compile time or only at runtime.

void ``basic_any` &` ``basic_any` &`

Exchange of the contents of `lhs` and `rhs`.

Nothing.

T

basic_any
&
T

basic_any
&&
T

const `basic_any` &
const ValueType *

const `basic_any` *
ValueType *

basic_any
*

Custom keyword cast for extracting a value of a given type from an ``basic_any``. Also available from `boost` namespace.

If passed a pointer, it returns a similarly qualified pointer to the value content if successful, otherwise null is returned. If T is ValueType, it returns a copy of the held value, otherwise, if T is a reference to (possibly const qualified) ValueType, it returns a reference to the held value.

Overloads taking an ``basic_any`` pointer do not throw; overloads taking an ``basic_any`` value or reference throw ``bad_any_cast`` if unsuccessful.

# Acknowledgements

Doug Gregor ported the documentation to the BoostBook format.