class Poco::Dynamic::Var

Overview

Var allows to store data of different types and to convert between these types transparently. More…

#include <Var.h>

class Var
{
public:
    // typedefs

    typedef SharedPtr<Var> Ptr;
    typedef Poco::Dynamic::VarIterator Iterator;
    typedef const VarIterator ConstIterator;

    // construction

    Var();

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

    Var(const char* pVal);
    Var(const Var& other);

    // methods

    void
    swap(Var& other);

    ConstIterator
    begin() const;

    ConstIterator
    end() const;

    Iterator
    begin();

    Iterator
    end();

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

    template <typename T>
    T
    convert() const;

    template <typename T>
    operator T() const;

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

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

    bool
    operator!() const;

    Var&
    operator=(const Var& other);

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

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

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

    Var&
    operator++();

    const Var
    operator++(int);

    Var&
    operator--();

    const Var
    operator--(int);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    bool
    operator<(const Var& other) const;

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

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

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

    bool
    operator>(const Var& other) const;

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

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

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

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

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

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

    bool
    isArray() const;

    bool
    isVector() const;

    bool
    isList() const;

    bool
    isDeque() const;

    bool
    isStruct() const;

    char&
    at(std::size_t n);

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

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

    Var&
    operator[](const std::string& name);

    const Var&
    operator[](const std::string& name) const;

    const std::type_info&
    type() const;

    void
    empty();

    bool
    isEmpty() const;

    bool
    isInteger() const;

    bool
    isSigned() const;

    bool
    isNumeric() const;

    bool
    isBoolean() const;

    bool
    isString() const;

    std::size_t
    size() const;

    std::string
    toString() const;

    static
    Var
    parse(const std::string& val);

    static
    std::string
    toString(const Var& var);
};

Detailed Documentation

Var allows to store data of different types and to convert between these types transparently.

Var 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”) Var 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 Var ‘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 decrement (--)

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

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

Construction

Var()

Creates an empty Var.

template <typename T>
Var(const T& val)

Creates the Var from the given value.

Var(const Var& other)

Copy constructor.

Methods

void
swap(Var& other)

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

ConstIterator
begin() const

Returns the const Var iterator.

ConstIterator
end() const

Returns the const Var iterator.

Iterator
begin()

Returns the Var iterator.

Iterator
end()

Returns the Var iterator.

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

Invoke this method to perform a safe conversion.

Example usage:

Var 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 Var is empty.

template <typename T>
T
convert() const

Invoke this method to perform a safe conversion.

Example usage:

Var 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 Var is empty.

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 Var is empty.

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 Var is empty.

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

Assignment operator for assigning POD to Var.

bool
operator!() const

Logical NOT operator.

Var&
operator=(const Var& other)

Assignment operator specialization for Var.

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

Addition operator for adding POD to Var.

const Var
operator+(const Var& other) const

Addition operator specialization for Var.

const Var
operator+(const char* other) const

Addition operator specialization for adding const char* to Var.

Var&
operator++()

Pre-increment operator.

const Var
operator++(int)

Post-increment operator.

Var&
operator--()

Pre-decrement operator.

const Var
operator--(int)

Post-decrement operator.

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

Addition asignment operator for addition/assignment of POD to Var.

Var&
operator+=(const Var& other)

Addition asignment operator overload for Var.

Var&
operator+=(const char* other)

Addition asignment operator overload for const char*.

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

Subtraction operator for subtracting POD from Var.

const Var
operator-(const Var& other) const

Subtraction operator overload for Var.

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

Subtraction asignment operator.

Var&
operator-=(const Var& other)

Subtraction asignment operator overload for Var.

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

Multiplication operator for multiplying Var with POD.

const Var
operator*(const Var& other) const

Multiplication operator overload for Var.

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

Multiplication asignment operator.

Var&
operator*=(const Var& other)

Multiplication asignment operator overload for Var.

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

Division operator for dividing Var with POD.

const Var
operator/(const Var& other) const

Division operator overload for Var.

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

Division asignment operator.

Var&
operator/=(const Var& other)

Division asignment operator specialization for Var.

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

Equality operator.

bool
operator==(const char* other) const

Equality operator overload for const char*.

bool
operator==(const Var& other) const

Equality operator overload for Var.

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

Inequality operator.

bool
operator!=(const Var& other) const

Inequality operator overload for Var.

bool
operator!=(const char* other) const

Inequality operator overload for const char*.

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

Less than operator.

bool
operator<(const Var& other) const

Less than operator overload for Var.

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

Less than or equal operator.

bool
operator<=(const Var& other) const

Less than or equal operator overload for Var.

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

Greater than operator.

bool
operator>(const Var& other) const

Greater than operator overload for Var.

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

Greater than or equal operator.

bool
operator>=(const Var& other) const

Greater than or equal operator overload for Var.

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

Logical OR operator.

bool
operator||(const Var& other) const

Logical OR operator operator overload for Var.

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

Logical AND operator.

bool
operator&&(const Var& other) const

Logical AND operator operator overload for Var.

bool
isArray() const

Returns true if Var is not empty.

bool
isVector() const

Returns true if Var represents a vector.

bool
isList() const

Returns true if Var represents a list.

bool
isDeque() const

Returns true if Var represents a deque.

bool
isStruct() const

Returns true if Var represents a struct.

char&
at(std::size_t n)

Returns character at position n.

This function only works with Var containing a std::string.

Var&
operator[](const std::string& name)

Index operator by name, only use on Vars where isStruct returns true! In all other cases InvalidAccessException is thrown.

const Var&
operator[](const std::string& name) const

Index operator by name, only use on Vars where isStruct returns true! In all other cases InvalidAccessException is thrown.

const std::type_info&
type() const

Returns the type information of the stored content.

void
empty()

Empties Var.

bool
isEmpty() const

Returns true if empty.

bool
isInteger() const

Returns true if stored value is integer.

bool
isSigned() const

Returns true if stored value is signed.

bool
isNumeric() const

Returns true if stored value is numeric.

Returns false for numeric strings (e.g. “123” is string, not number)

bool
isBoolean() const

Returns true if stored value is boolean.

Returns false for boolean strings (e.g. “true” is string, not number)

bool
isString() const

Returns true if stored value is std::string.

std::size_t
size() const

Returns the size of this Var.

This function returns 0 when Var is empty, 1 for POD or the size (i.e. length) for held container.

std::string
toString() const

Returns the stored value as string.

static
Var
parse(const std::string& val)

Parses the string which must be in JSON format.

static
std::string
toString(const Var& var)

Converts the Var to a string in JSON format.

Note that toString(const Var&) will return a different result than Var::convert<std::string>() and Var::toString()!

Table of Contents

Previous topic

Next topic

class Poco::Dynamic::Var

Overview

Detailed Documentation

Construction

Methods