Class Poco::DynamicAny
Author: Applied Informatics Software Engineering GmbH and Contributors
Date: 2009-11-24

# Poco

# class DynamicAny

Library: Foundation
Package: Core
Header: Poco/DynamicAny.h

## Description

DynamicAny allows to store data of different types and to convert between these types transparently. DynamicAny puts forth the best effort to provide intuitive and reasonable conversion semantics and prevent unexpected data loss, particularly when performing narrowing or signedness conversions of numeric data types.

An attempt to convert or extract from a non-initialized (empty) DynamicAny variable shall result in an exception being thrown.

Loss of signedness is not allowed for numeric values. This means that if an attempt is made to convert the internal value which is a negative signed integer to an unsigned integer type storage, a RangeException is thrown. Overflow is not allowed, so if the internal value is a larger number than the target numeric type size can accomodate, a RangeException is thrown.

Precision loss, such as in conversion from floating-point types to integers or from double to float on platforms where they differ in size (provided internal actual value fits in float min/max range), is allowed.

String truncation is allowed — it is possible to convert between string and character when string length is greater than 1. An empty string gets converted to the char '\0', a non-empty string is truncated to the first character.

Boolean conversion is performed as follows:

A string value "false" (not case sensitive), "0" or "" (empty string) can be converted to a boolean value false, any other string not being false by the above criteria evaluates to true (e.g: "hi" -> true). Integer 0 values are false, everything else is true. Floating point values equal to the minimal FP representation on a given platform are false, everything else is true.

Arithmetic operations with POD types as well as between DynamicAny's are supported, subject to following limitations:

- for std::string and const char* values, only '+' and '+=' operations are supported

- for integral and floating point numeric values, following operations are supported:

    '+', '+=', '-', '-=', '*', '*=' , '/' and '/='

- for integral values, following operations are supported:

    prefix and postfix increment (++) and decement (--)

- for all other types, InvalidArgumentException is thrown upon attempt of an arithmetic operation

A DynamicAny can be created from and converted to a value of any type for which a specialization of DynamicAnyHolderImpl is available. For supported types, see DynamicAnyHolder documentation.

## Member Summary

Member Functions: convert, empty, extract, isArray, isEmpty, isInteger, isNumeric, isSigned, isString, operator, operator !, operator !=, operator &&, operator *, operator *=, operator +, operator ++, operator +=, operator -, operator --, operator -=, operator /, operator /=, operator <, operator <=, operator =, operator ==, operator >, operator >=, operator T, operator ||, swap, type

## Constructors

### DynamicAny

DynamicAny();

Creates an empty DynamicAny.

### DynamicAny

template < typename T > DynamicAny(
const T & val
);

Creates the DynamicAny from the given value.

### DynamicAny

DynamicAny(
const char * pVal
);

### DynamicAny

DynamicAny(
const DynamicAny & other
);

Copy constructor.

## Destructor

### ~DynamicAny

~DynamicAny();

Destroys the DynamicAny.

## Member Functions

### convert

template < typename T > void convert(
T & val
) const;

Invoke this method to perform a safe conversion.

Example usage:

    DynamicAny any("42");
    int i;
    any.convert(i);

Throws a RangeException if the value does not fit into the result variable. Throws a NotImplementedException if conversion is not available for the given type. Throws InvalidAccessException if DynamicAny is empty.

### convert

template < typename T > T convert() const;

Invoke this method to perform a safe conversion.

Example usage:

    DynamicAny any("42");
    int i = any.convert<int>();

Throws a RangeException if the value does not fit into the result variable. Throws a NotImplementedException if conversion is not available for the given type. Throws InvalidAccessException if DynamicAny is empty.

### empty

void empty();

Empties DynamicAny.

### extract

template < typename T > const T & extract() const;

Returns a const reference to the actual value.

Must be instantiated with the exact type of the stored value, otherwise a BadCastException is thrown. Throws InvalidAccessException if DynamicAny is empty.

### isArray

bool isArray() const;

Returns true if DynamicAny represents a vector

### isEmpty

bool isEmpty() const;

Returns true if empty.

### isInteger

bool isInteger() const;

Returns true if stored value is integer.

### isNumeric

bool isNumeric() const;

Returns true if stored value is numeric. Returns false for numeric strings (e.g. "123" is string, not number)

### isSigned

bool isSigned() const;

Returns true if stored value is signed.

### isString

bool isString() const;

Returns true if stored value is std::string.

### operator

template < typename T > DynamicAny & operator[] (
T n
);

Index operator, only use on DynamicAnys where isArray returns true! In all other cases InvalidAccessException is thrown.

### operator

template < typename T > const DynamicAny & operator[] (
T n
) const;

const Index operator, only use on DynamicAnys where isArray returns true! In all other cases InvalidAccessException is thrown.

### operator !

bool operator ! () const;

Logical NOT operator.

### operator !=

template < typename T > bool operator != (
const T & other
) const;

Inequality operator

### operator !=

bool operator != (
const DynamicAny & other
) const;

Inequality operator overload for DynamicAny

### operator !=

bool operator != (
const char * other
) const;

Inequality operator overload for const char*

### operator &&

template < typename T > bool operator && (
const T & other
) const;

Logical AND operator

### operator &&

bool operator && (
const DynamicAny & other
) const;

Logical AND operator operator overload for DynamicAny

### operator *

template < typename T > const DynamicAny operator * (
const T & other
) const;

Multiplication operator for multiplying DynamicAny with POD

### operator *

const DynamicAny operator * (
const DynamicAny & other
) const;

Multiplication operator overload for DynamicAny

### operator *=

template < typename T > DynamicAny & operator *= (
const T & other
);

Multiplication assignment operator

### operator *=

DynamicAny & operator *= (
const DynamicAny & other
);

Multiplication assignment operator overload for DynamicAny

### operator +

template < typename T > const DynamicAny operator + (
const T & other
) const;

Addition operator for adding POD to DynamicAny

### operator +

const DynamicAny operator + (
const DynamicAny & other
) const;

Addition operator specialization for DynamicAny

### operator +

const DynamicAny operator + (
const char * other
) const;

Addition operator specialization for adding const char* to DynamicAny

### operator ++

DynamicAny & operator ++ ();

Pre-increment operator

### operator ++

const DynamicAny operator ++ (
int
);

Post-increment operator

### operator +=

template < typename T > DynamicAny & operator += (
const T & other
);

Addition assignment operator for addition/assignment of POD to DynamicAny.

### operator +=

DynamicAny & operator += (
const DynamicAny & other
);

Addition assignment operator overload for DynamicAny

### operator +=

DynamicAny & operator += (
const char * other
);

Addition assignment operator overload for const char*

### operator -

template < typename T > const DynamicAny operator - (
const T & other
) const;

Subtraction operator for subtracting POD from DynamicAny

### operator -

const DynamicAny operator - (
const DynamicAny & other
) const;

Subtraction operator overload for DynamicAny

### operator --

DynamicAny & operator -- ();

Pre-decrement operator

### operator --

const DynamicAny operator -- (
int
);

Post-decrement operator

### operator -=

template < typename T > DynamicAny & operator -= (
const T & other
);

Subtraction assignment operator

### operator -=

DynamicAny & operator -= (
const DynamicAny & other
);

Subtraction assignment operator overload for DynamicAny

### operator /

template < typename T > const DynamicAny operator / (
const T & other
) const;

Division operator for dividing DynamicAny with POD

### operator /

const DynamicAny operator / (
const DynamicAny & other
) const;

Division operator overload for DynamicAny

### operator /=

template < typename T > DynamicAny & operator /= (
const T & other
);

Division assignment operator

### operator /=

DynamicAny & operator /= (
const DynamicAny & other
);

Division assignment operator specialization for DynamicAny

### operator <

template < typename T > bool operator < (
const T & other
) const;

Less than operator

### operator <

bool operator < (
const DynamicAny & other
) const;

Less than operator overload for DynamicAny

### operator <=

template < typename T > bool operator <= (
const T & other
) const;

Less than or equal operator

### operator <=

bool operator <= (
const DynamicAny & other
) const;

Less than or equal operator overload for DynamicAny

### operator =

template < typename T > DynamicAny & operator = (
const T & other
);

Assignment operator for assigning POD to DynamicAny

### operator =

DynamicAny & operator = (
const DynamicAny & other
);

Assignment operator specialization for DynamicAny

### operator ==

template < typename T > bool operator == (
const T & other
) const;

Equality operator

### operator ==

bool operator == (
const char * other
) const;

Equality operator overload for const char*

### operator ==

bool operator == (
const DynamicAny & other
) const;

Equality operator overload for DynamicAny

### operator >

template < typename T > bool operator > (
const T & other
) const;

Greater than operator

### operator >

bool operator > (
const DynamicAny & other
) const;

Greater than operator overload for DynamicAny

### operator >=

template < typename T > bool operator >= (
const T & other
) const;

Greater than or equal operator

### operator >=

bool operator >= (
const DynamicAny & other
) const;

Greater than or equal operator overload for DynamicAny

### operator T

template < typename T > operator T() const;

Safe conversion operator for implicit type conversions. If the requested type T is same as the type being held, the operation performed is direct extraction, otherwise it is the conversion of the value from type currently held to the one requested.

Throws a RangeException if the value does not fit into the result variable. Throws a NotImplementedException if conversion is not available for the given type. Throws InvalidAccessException if DynamicAny is empty.

### operator ||

template < typename T > bool operator || (
const T & other
) const;

Logical OR operator

### operator ||

bool operator || (
const DynamicAny & other
) const;

Logical OR operator operator overload for DynamicAny

### swap

void swap(
DynamicAny & other
);

Swaps the content of the this DynamicAny with the other DynamicAny.

### type

const std::type_info & type() const;

Returns the type information of the stored content.