Poco::Dynamic

class Var

Library: Foundation
Package: Dynamic
Header: Poco/Dynamic/Var.h

Description

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 accommodate, 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.

Member Summary

Member Functions: at, begin, clear, convert, empty, end, extract, isArray, isBoolean, isDate, isDateTime, isDeque, isEmpty, isInteger, isList, isNumeric, isOrdered, isSigned, isString, isStruct, isTime, isUUID, isVector, operator !, operator !=, operator &&, operator *, operator *=, operator +, operator ++, operator +=, operator -, operator --, operator -=, operator /, operator /=, operator <, operator <=, operator =, operator ==, operator >, operator >=, operator T, operator [], operator ||, parse, size, swap, toString, type, typeName

Types Aliases

ConstIterator

using ConstIterator = const VarIterator;

Iterator

using Iterator = Poco::Dynamic::VarIterator;

Ptr

using Ptr = SharedPtr < Var >;

Constructors

Var

Var();

Creates an empty Var.

Var inline

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

Creates the Var from the given value.

Var

Var(
    const char * pVal
);

Var

Var(
    const Var & other
);

Copy constructor.

Destructor

~Var

~Var();

Destroys the Var.

Member Functions

at

char & at(
    std::size_t n
);

Returns character at position n. This function only works with Var containing a std::string.

begin inline

ConstIterator begin() const;

Returns the const Var iterator.

begin

Iterator begin();

Returns the Var iterator.

clear

void clear();

Empties Var.

convert inline

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.

convert inline

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.

empty

void empty();

Empties Var. This function is deprecated and will be removed. Please use clear().

end inline

ConstIterator end() const;

Returns the const Var iterator.

end

Iterator end();

Returns the Var iterator.

extract inline

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.

isArray inline

bool isArray() const;

Returns true if Var is an array.

isBoolean inline

bool isBoolean() const;

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

isDate inline

bool isDate() const;

Returns true if stored value represents a date.

isDateTime inline

bool isDateTime() const;

Returns true if stored value represents a date/time.

isDeque inline

bool isDeque() const;

Returns true if Var represents a deque.

isEmpty inline

bool isEmpty() const;

Returns true if empty.

isInteger inline

bool isInteger() const;

Returns true if stored value is integer.

isList inline

bool isList() const;

Returns true if Var represents a list.

isNumeric inline

bool isNumeric() const;

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

isOrdered inline

bool isOrdered() const;

Returns true if Var represents an ordered struct, false if struct is sorted.

isSigned inline

bool isSigned() const;

Returns true if stored value is signed.

isString inline

bool isString() const;

Returns true if stored value is std::string.

isStruct inline

bool isStruct() const;

Returns true if Var represents a struct.

isTime inline

bool isTime() const;

Returns true if stored value represents time or date/time.

isUUID inline

bool isUUID() const;

Returns true if stored value is a Poco::UUID.

isVector inline

bool isVector() const;

Returns true if Var represents a vector.

operator ! inline

bool operator ! () const;

Logical NOT operator.

operator != inline

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

Inequality operator

operator !=

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

Inequality operator overload for Var

operator !=

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

Inequality operator overload for const char*

operator && inline

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

Logical AND operator.

operator &&

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

Logical AND operator operator overload for Var.

operator * inline

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

Multiplication operator for multiplying Var with POD

operator *

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

Multiplication operator overload for Var

operator *= inline

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

Multiplication assignment operator

operator *=

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

Multiplication assignment operator overload for Var

operator + inline

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

Addition operator for adding POD to Var

operator +

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

Addition operator specialization for Var

operator +

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

Addition operator specialization for adding const char* to Var

operator ++

Var & operator ++ ();

Pre-increment operator

operator ++

const Var operator ++ (
    int
);

Post-increment operator

operator += inline

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

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

operator +=

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

Addition assignment operator overload for Var

operator +=

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

Addition assignment operator overload for const char*

operator - inline

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

Subtraction operator for subtracting POD from Var

operator -

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

Subtraction operator overload for Var

operator --

Var & operator -- ();

Pre-decrement operator

operator --

const Var operator -- (
    int
);

Post-decrement operator

operator -= inline

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

Subtraction assignment operator

operator -=

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

Subtraction assignment operator overload for Var

operator / inline

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

Division operator for dividing Var with POD

operator /

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

Division operator overload for Var

operator /= inline

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

Division assignment operator

operator /=

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

Division assignment operator specialization for Var

operator < inline

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

Less than operator

operator <

bool operator < (
    const Var & other
) const;

Less than operator overload for Var

operator <= inline

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

Less than or equal operator

operator <=

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

Less than or equal operator overload for Var

operator = inline

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

Assignment operator for assigning POD to Var

operator =

Var & operator = (
    const Var & other
);

Assignment operator specialization for Var

operator == inline

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 Var & other
) const;

Equality operator overload for Var

operator > inline

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

Greater than operator

operator >

bool operator > (
    const Var & other
) const;

Greater than operator overload for Var

operator >= inline

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

Greater than or equal operator

operator >=

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

Greater than or equal operator overload for Var

operator T inline

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.

operator [] inline

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

operator [] inline

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

operator []

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.

operator []

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.

operator || inline

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

Logical OR operator

operator ||

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

Logical OR operator operator overload for Var

parse static

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

Parses the string which must be in JSON format

size inline

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.

swap inline

void swap(
    Var & other
);

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

toString

std::string toString() const;

Returns the stored value as string.

toString static

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()!

type inline

const std::type_info & type() const;

Returns the type information of the stored content.

typeName inline

std::string typeName(
    bool demangle = true
) const;

Returns the type name of the stored content. If demangling is available and emangle is true, the returnsed string will be demangled.

POCO C++ Libraries 1.14.0-all
Copyright © 2024, Applied Informatics Software Engineering GmbH and Contributors