|
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.
static template <class T> void 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 T> void 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 T> bool Is() const
Returns true if Value contains exactly type T.
template <class T> const 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 T> const 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
std::string ToStd() const
std::wstring ToWStd() 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)
Value(const std::string& s)
Value(const std::wstring& s)
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& v) const
bool operator!=(const Value& v) const
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& v) const
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& v) const
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& x) const
Same as Compare(x) <= 0.
bool operator>=(const Value& x) const
Same as Compare(x) >= 0.
bool operator<(const Value& x) const
Same as Compare(x) < 0.
bool operator>(const Value& x) const
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 i) const
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& key) const
const Value& operator[](const char *key) const
const Value& operator[](const Id& key) const
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 T> Value& 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.
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:
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.
template <class T> bool FitsSvoValue()
Returns true if sizeof(T) fits into SVO Value optimization.
template <class T> Value 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 T> Value 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 T> Value RawToValue(const T& data)
Creates Raw Value from data. T has to have deep copy constructor.
template <class T> Value 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 T> Value RawDeepToValue(const T& data)
Creates Raw Value by using optional deep copy constructor (T(const T&, int)) data.
template <class T> T& 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.
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.
|
