Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site













SourceForge.net Logo

Value

 

class Value : private Moveable<Value

Value is a concrete value type (with normal deep copy semantics) that is designed to store other concrete types in unified way, but in fact can store almost any other data type.

 

There are two basic levels of Value compatibility. Data can be stored to Value as "raw" - that means that only working operations for such Value are test that Value contains value of such type and extracting a constant reference to the stored Value.

 

"Rich" Value types provide more unified functionality: Comparison, hashing, serialization, jsonization, xmlization, Null testing, conversion to text etc. Rich type also provide some level of conversion compatibility: e.g. Value containing integer can be extracted to double. Note that Value containing Null can be (usually) extracted to any compatible type (e.g. Null Date can be assigned to integer).

 

For optimization purposes, there are two subgroups of "Rich" types - normal ones, and "SVO" (as in "Small Value Optimization"). SVO types have some restrictions: they have to be PODs and they have to fit to 8 bytes; such types are stored more efficiently (they are stored directly in Value body, whereas other values are stored indirectly using reference counted pointer).

 

Basic Value class provides support for some fundamental types and "standard Value" types: bool, int, int64, double, String, WString, Date and Time. There are also special types Void (for empty Value) and ErrorValue (represents error). Important feature is that ErrorValue is considered to be Void and Void is considered to be Null (but not vice verse).

 

To make some concrete type Value compatible, the standard way is to derive it from helper class ValueType, which assigns value type number constant and defines "empty" methods for rich value features. It is also required to Register (or SvoRegister) the Value so that it can be successfully deserialized from stream or decoded from JSON or XML.

 

 

Public Method List

 

static template <class Tvoid Register(const char *name = NULL)

Registers the type T as Rich Value type. name is the name to be used with JSON or XML.

 


 

static template <class Tvoid SvoRegister(const char *name = NULL)

Registers the type T as SVO Rich Value type. name is the name to be used with JSON or XML.

 


 

dword GetType() const

Returns the type number (assigned by derivation from ValueType).

 


 

bool IsError() const

Returns true if Value contains ErrorValue.

 


 

bool IsVoid() const

Returns true if Value is void (default constructed Value is void). IsError implies IsVoid.

 


 

bool IsNull() const

Returns true if Value is Null. IsVoid implies IsNull.

 


 

template <class Tbool Is() const

Returns true if Value contains exactly type T.

 


 

template <class Tconst T& To() const

Returns constant reference to data contained in Value if Is<T> is true, otherwise throws ValueTypeError exception. Undefined if Value contains ValueArray or ValueMap (technical and performance reasons).

 


 

template <class Tconst T& Get() const

Returns constant reference to data contained in Value. Unlike To, it also works if Value contains Null of any type, in that case it returns a reference to Null of type T. If Value does not contain T, throws ValueTypeError. Undefined if Value contains ValueArray or ValueMap (technical and performance reasons).

 


 

operator String() const

operator WString() const

operator Date() const

operator Time() const

operator double() const

operator int() const

operator int64() const

operator bool() const

Value(const String& s)

Value(const WString& s)

Value(const char *s)

Value(int i)

Value(int64 i)

Value(double d)

Value(bool b)

Value(Date d)

Value(Time t)

Support of direct T->Value and Value->T conversions of standard Value types. If conversion is not possible, throws ValueTypeError.

 


 

Value(const Nuller&)

Support for assignment from Null (e.g. Value v = Null). Creates Value containing (int)Null.

 


 

bool operator==(const Value& vconst

bool operator!=(const Value& vconst

Equality comparison for supporting rich types. Note that by defining IsPolyEqual function for the type, it is possible to compare Value containing different concrete types, e.g. double with int (U++ types, viable IsPolyEqual functions are already defined).

 


 

bool IsSame(const Value& vconst

ValueMap is ordered and is compared as such, which means that even if values of keys are the same, if order is different, ValueMaps or Values containing them are not considered equal (as with operator==). This method provides and alternative comparison of Values which treats contained ValueMaps as unordered. It goes recursively through any contained ValueMaps and ValueArrays too, for other Value types than ValueMap it uses the normal operator==.

 


 

int Compare(const Value& vconst

Compares value with another value v. Types of values must be comparable (e.g. it is possible to compare texts with texts, numbers with numbers etc...). If types are not comparable, returns 0. If values are equal, returns 0, -1 if Value is lesser than v, 1 if Value if it is greater.

 


 

bool operator<=(const Value& xconst

Same as Compare(x) <= 0.

 


 

bool operator>=(const Value& xconst

Same as Compare(x) >= 0.

 


 

bool operator<(const Value& xconst

Same as Compare(x) < 0.

 


 

bool operator>(const Value& xconst

Same as Compare(x) > 0.

 


 

String ToString() const

Conversion to text for supporting rich types.

 


 

String operator ~() const

Same as ToString().

 


 

String GetTypeName() const

Returns the text with typename for debugging purposes.

 


 

void Serialize(Stream& s)

Serialization for supporting rich types.

 


 

void Xmlize(XmlIO& xio)

Conversion to/from XML for supporting rich types.

 


 

void Jsonize(JsonIO& jio)

Conversion for/from JSON for supporting rich types.

 


 

unsigned GetHashValue() const

Hashing for supporting rich types.

 


 

int GetCount() const

If Value contains ValueArray or ValueMap, returns a number of elements in it, otherwise 0.

 


 

const Value& operator[](int iconst

If Value contains ValueArray or ValueMap, returns an element at position i. If no such element exists or there is no ValueArray/ValueMap, behaviour is runtime error.

 


 

const Value& operator[](const String& keyconst

const Value& operator[](const char *keyconst

const Value& operator[](const Id& keyconst

If Value contains ValueMap and there is element with String key, returns its value. If not, returns void Value.

 


 

Value& At(int i)

If Value is Null, sets it to ValueArray. If Value is ValueArray or was Null, returns a reference of element at i , if there is none, adds as much Void Values to array as necessarry to have it. If Value is ValueMap, returns a reference to map value at i , if there is none, behaviour is undefined (ASSERT in debug mode fails). The reference returned is invalidated by any further use of originating Value. If Value is neither ValueArray, Null or ValueMap, behaviour is undefined (ASSERT in debug mode fails).

 


 

Value& operator()(int i)

Same as At(i).

 


 

void Add(const Value& src)

If Value is Null, sets it to ValueArray. If Value is ValueArray or was Null, appends src at the end of ArrayValue. If Value is neither ValueArray or Null, behaviour is undefined (ASSERT in debug mode fails).

 


 

template <typename TValue& operator<<(const T& src)

Same as Add(src).

 


 

Value& GetAdd(const Value& key)

If Value is Null, sets it to ValueMap. If Value is ValueArray, sets it to standard conversion of ValueMap to ValueArray (indicies become keys). If Value is ValueMap or was Null, returns a reference of element at key key, if there is none, it is created as Void Value. The reference returned is invalidated by any further use of originating Value. If Value is neither ValueArray, Null or ValueMap, behaviour is undefined (ASSERT in debug mode fails).

 


 

Value& operator()(const String& key)

Same as GetAdd(key).

 


 

Value& operator()(const char *key)

Save as GetAdd(key).

 


 

Value& operator()(const Id& key)

Save as GetAdd(key).

 


 

Value& operator=(const Value& v)

Assignment.

 


 

Value(const Value& v)

Copy constructor.

 


 

Value()

Default constructor, creates void Value.

 


 

~Value()

Destructor.

 

 

ValueType

 

template <class T, dword type, class B = EmptyClass>

class ValueType : public B

ValueType is a helper class intended for creation of client code custom Value rich compatible concrete types. Such types should derive from this class, which serves to

 

assign Value type number to the concrete class (parameter type)

predefines some rich specific methods as 'empty' for the class. Derived type thus can only implement methods it needs (e.g. that required for client code).

adds conversion operator to implement Ref (generic reference) compatibility

 

The list of 'empty' methods of ValueType thus also serves as list of methods that Value compatible concrete type might define to gain support of certain operations with Value:

 

Public Method List

 

bool IsNullInstance() const

True if concrete type contains Null value. ValueType returns false.

 


 

void Serialize(Stream& s)

Serialization support. ValueType invokes runtime error.

 


 

void Xmlize(XmlIO& xio)

XML support. ValueType invokes runtime error.

 


 

void Jsonize(JsonIO& jio)

JSON support. ValueType invokes runtime error.

 


 

unsigned GetHashValue() const

Hash value of contained data. ValueType return 0.

 


 

bool operator==(const T&const

Equality of data. ValueType invokes runtime error.

 


 

String ToString() const

Conversion to text. ValueType returns empty String.

 


 

int Compare(const T&const

Comparison with another value of the same type. Returns should return -1, 0, 1.

 


 

int PolyCompare(const Value&const

Polymorphic comparison with different type.

 


 

operator Ref()

Returns a Ref (generic reference) to the instance of T.

 

Value support functions

 

Value creation

 

template <class Tbool FitsSvoValue()

Returns true if sizeof(T) fits into SVO Value optimization.

 


 

template <class TValue SvoToValue(const T& x)

Creates SVO Value from x. T has to have defined all that is required for Value compatibility (derivation from ValueType takes care of this). Unlike RawToValue, SvoToValue should only be used in client's type operator Value() - to avoid casting issues between Rich and Svo kinds.

 


 

template <class TValue RichToValue(const T& data)

Creates Rich Value from data. T has to have defined all that is required for Value compatibility (derivation from ValueType takes care of this). Unlike RawToValue, RichToValue should only be used in client's type operator Value() - to avoid casting issues between Rich and Svo kinds.

 


 

template <class TValue RawToValue(const T& data)

Creates Raw Value from data. T has to have deep copy constructor.

 


 

template <class TValue RawPickToValue(pick_ T& data)

Creates Raw Value by picking data (data is destroyed in the process). T has to have pick copy semantics.

 


 

template <class TValue RawDeepToValue(const T& data)

Creates Raw Value by using optional deep copy constructor (T(const T&, int)) data.

 


 

template <class TT& CreateRawValue(Value& v)

Creates Raw Value of type T in v. T is created using default constructor and reference to created instance is returned. Client code should setup this instance before v is passed elsewhere.

 


 

Value ErrorValue(const char *s)

Value ErrorValue(const String& s)

Returns Error Value with description s.

 


 

const Value& ErrorValue()

Returns ErrorValue with empty description.

 

 

Value type tests

 

bool IsVoid(const Value& v)

Same as v.IsVoid().

 


 

bool IsError(const Value& v)

Same as v.IsError().

 


 

bool IsString(const Value& v)

Returns true if v contains String, WString or Null value.

 


 

bool IsNumber(const Value& v)

Returns true if v contains bool, int, int64, double or Null value.

 


 

bool IsDateTime(const Value& v)

Returns true if v contains Date, Time or Null value.

 


 

bool IsValueArray(const Value& v)

Returns true v contains ValueArray or ValueMap.

 


 

bool IsValueMap(const Value& v)

Returns true v contains ValueArray or ValueMap.

 


 

String GetErrorText(const Value& v)

If v is Error Value, returns error description, otherwise empty String.

 


 

bool IsNull(const Value& v)

Same as v.IsNull().

 


 

const Value& Nvl(const Value& a, const Value& b)

If a.IsNull(), returns b, otherwise (a not null) returns a.

 

Last edit by cxl on 03/07/2017. Do you want to contribute?. T++