any

• Motivation
• Examples
• Synopsis
• ValueType requirements
• any
• bad_any_cast
• any_cast
• Portability
• Future directions

Motivation

1. 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.
2. 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.
3. 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.

Examples

using namespace std;
using namespace boost;

list<any> values;

void append_int(int value)
{
    any to_append = value;
    values.push_back(to_append);
}

void append_string(const string & value)
{
    values.push_back(value);
}

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

void append_any(const any & value)
{
    values.push_back(value);
}

void append_nothing()
{
    values.push_back(any());
}

bool is_empty(const any & operand)
{
    return operand;
}

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

bool is_char_ptr(const any & operand)
{
    const char * unused;
    return operand.copy_to(unused);
}

bool is_string(const any & operand)
{
    return operand.to_ptr<string>();
}

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

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

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

typedef list<property> properties;

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

Synopsis

#include <typeinfo>

namespace boost
{
    class any;
    class bad_any_cast;
    template<typename ValueType>
      ValueType any_cast(const any &);
}

ValueType requirements

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 any are:

• A ValueType is CopyConstructible [20.1.3].
• A ValueType is optionally Assignable [23.1]. Only any::copy_to requires this optional capability.
• The destructor for a ValueType does not throw any exceptions.

any

class any
{
public: // structors

    any();
    any(const any &);
    template<typename ValueType>
      any(const ValueType &);
    ~any();

public: // modifiers

    any & swap(any &);
    any & operator=(const any &);
    template<typename ValueType>
      any & operator=(const ValueType &);

public: // queries

    operator const void *() const;
    const std::type_info & type() const;
    template<typename ValueType>
      bool copy_to(ValueType &) const;
    template<typename ValueType>
      ValueType * to_ptr();
    template<typename ValueType>
      const ValueType * to_ptr() const;

private: // representation
    ...
};

---

Structors

any::any();

Default constructor that sets new instance to empty.

any::any(const any & other);

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.

template<typename ValueType>
  any::any(const ValueType & value);

Templated constructor makes a copy of value, so that the initial content of the new instance is equivalent in both type and value to value. May fail with a std::bad_alloc exception or any exceptions arising from the copy constructor of the contained type.

any::~any();

Non-throwing destructor that releases any and all resources used in management of instance.

---

Modifiers

any & swap(any & rhs);

Non-throwing swap of the contents of *this and rhs.

any & operator=(const any & rhs);

Copy assignment operator that 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 is empty. May fail with a std::bad_alloc exception or any exceptions arising from the copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

template<typename ValueType>
  any & operator=(const ValueType & rhs);

Templated assignment operator makes a copy of rhs, discarding previous content, so that the new content of is equivalent in both type and value to rhs. May fail with a std::bad_alloc exception or any exceptions arising from the copy constructor of the contained type. Assignment satisfies the strong guarantee of exception safety.

---

Queries

operator const void *() const;

Test for emptiness, returning null if instance is empty, otherwise a single, unspecified non-null pointer.

const std::type_info & type() const;

Returns the typeid of the contained value if instance is non-empty, otherwise typeid(void) returned. Useful for querying against types known either at compile time or only at runtime.

template<typename ValueType>
  bool copy_to(ValueType & value) const;

Extraction of instance content by assignment. Returns true and assigns content of instance to value if typeid(ValueType) == type(), otherwise returns false and does not modify value. This combined test and assign value form can be more concise than either any::to_ptr or any_cast where a variable assignment is required, but exception handling or additional variable declarations would be considered verbose.

template<typename ValueType>
  ValueType * to_ptr();
template<typename ValueType>
  const ValueType * to_ptr() const;

Extraction of pointer to instance content. Returns a correctly cast pointer to the contained value if typeid(ValueType) == type(), otherwise returns null. Top-level cv-qualification of ValueType is ignored. to_ptr is used normally for extracting content without a strong assumption that the query will succeed. It can also be used to support type queries against a type known at compile time.

bad_any_cast

class bad_any_cast : public std::bad_cast
{
public:
    virtual const char * what() const;
};

any_cast

template<typename ValueType>
  ValueType any_cast(const any & operand);

Portability

Future directions