Var Class Reference

Detailed Description

A Var is a type that can hold a value of one of several types, similarly to a var in JavaScript.

Upon assignment to a number, string, bool, array or dic, it will take its value and type. If a Var is not initialized and operator var["string"] is used, it will be converted to a Dic and the given element returned. If operator var[int] is used on it, it will be converted to an array and the indexed element returned after an automatic resize to avoid overflow.

A Var can be constructed from a variable of type int, float, double, bool, String, Array or Dic, and will take its value and type. A default-constructed Var has type NONE.

Var z;            // z.type() = NONE
Var a = 3;        // a.type() = INT
Var b = 3.5;      // b.type() = NUMBER
Var s = "x";      // s.type() = STRING
Var t = true;     // t.type() = BOOL
Var n = Var::NUL; // n.type() = NUL

An array can be constructed from an existing Array<T> or by specifying its elements:

Var pair;
pair.resize(2);  // pair.type() = ARRAY,  pair.length() = 2
pair[0] = 1;
pair[1] = -2;

Arrays can also be created in one statement with one of these pseudo-literal syntaxes:

Var coords = array<Var>(10, 25, -1);       // up to 6 elements
Var indices = (Var(), 1, 3, 0, 2, -1);     // any number of elements (but is slower)
Var numbers = {1, 3, 9, -2};               // on C++11 compilers, for all same type elements
Var items = Var::array({1, "a", 9.5, -2}); // on C++11 compilers, for different types

An object can be constructed from an existing Dic<T> or by adding elements to a Var with var["key"]:

Var person;
person["name"] = "John";  // person.type() = OBJ
person["age"] = 21;

Alternatively, objects can be created in one statement with a pseudo-literal syntax:

Var particle = Var("name", "particle1")
                  ("x", 15.0)
                  ("y", -1.25)
                  ("visible", true)
                  ("color", array<Var>(255, 0, 255));

Or in C++11:

Var particle {
    { "name", "particle1" },
    { "x", 15.0 },
    { "y", -1.25 },
    { "visible", true },
    { "color", {255, 0, 255} }
};

Any combination of the above can be used to create complex structured vars.

A var can be checked for its type with the is() function or whether it contains a given key (if it is a Map), or if it contains a given item (if it is an Array):

if(a.is(Var::NUMBER)) {...} // INTs are NUMBERs too!
if(particle.has("name")) {...} // particle is an OBJ and has a "name" property
if(particle.has("visible", Var::BOOL)) {...} // point is an OBJ and has a bool property named "visible"
if(indices.contains(3)) {...} // indices is an array and contains number 3

Iteration

When a Var contains an array or an object, its elements or properties can be iterated.

Arrays can be iterated with foreach loops, or for(item : array) in C++11, or using array indexing and the length() method:

Var numbers = array<Var>(10.1, 25, -1, 3.4);
 
foreach(Var& x, numbers) // old way
{
    do_something_with(x);
}
 
for(auto& x : numbers)  // since C++11
{
    do_something_with(x);
}
 
for(int i=0; i < numbers.length(); i++)
{
    do_something_with(numbers[i]);
}

Object properties (keys and values) can be iterated with a foreach2 loop, or with range-based for in C++11/17 (but in this case don't forget to add .object()):

foreach2(String& key, Var& value, particle)   // old way
{
    printf("%s : %s\n", *key, *value.toString());
}
 
for(auto& e : particle.object())   // since C++11
{
    printf("%s : %s\n", *e.key, *e.value.toString());
}
 
for(auto& [key, value] : particle.object())   // C++17
{
    printf("%s : %s\n", *key, *value.toString());
}

Any Var can be converted to a String representation for example for printing on a console or to a file. This is done with the toString() method. For instance, the following:

printf("%s\n", *particle.toString());

will print the string:

{color=[255,0,255],name=particle1,visible=Y,x=15,y=-1.25}

For a better representation that can be parsed back into a Var, you can use XDL (Xdl::encode(var)) or JSON (Json::encode(var)).

#include <Var.h>

Public Member Functions
String	string () const
	Returns a string representation of this var.
Type	type () const
	Returns the internal type of this var.
Dic< Var >	object () const
	Returns the internal Dic if this var is an object.
Array< Var >	array () const
	Returns the internal Array if this var is an array.
	operator bool () const
	Returns the boolean value of this var (similar to JS conversion)
const char *	operator* () const
	Returns a char pointer to the beginning of the string if this var is a string; this is faster than calling .toString() but will not stringify numbers or other types.
template<class T >
Var	operator| (const T &v) const
	Returns the left value if it is defined or the right otherwise.
bool	ok () const
	Returns true if this var has a value (its type is not NONE)
Var &	operator, (const Var &x)
	Appends x to this var if this var is an array (useful for Var construction)
Var &	operator<< (const Var &x)
	Appends x to this var if this var is an array.
template<class T >
Var &	operator<< (const T &x)
	Appends x to this var if this var is an array.
Var &	extend (const Var &v)
	Adds keys and values from v to this var if it is an object, overwriting existing keys.
void	resize (int n)
	Resizes this var to n elements if this var is an array, converting if it was NONE.
const Var &	operator[] (int i) const
	Returns the element at index i if this var is an array.
Var &	operator[] (int i)
	Returns the element at index i if this var is an array, resizing the array if i is out of bounds.
Var &	operator[] (const String &key)
	Returns the property named key if this var is an object, creating it if it does not exist.
const Var &	operator[] (const String &key) const
	Returns the property named key if this var is an object.
Var	operator() (const String &key) const
	Returns a copy of the property named key if this var is an object, and never modifies the object.
Var *	getp (const String &key)
	Gets a pointer to the property named key if it exists or a null pointer otherwise.
template<class T >
Var &	operator() (const char *key, const T &v)
	Sets the value of property key of this var to v (Useful for Var construction)
Var &	operator[] (const char *key)
	Returns the property named key if this var is an object.
const Var &	operator[] (const char *key) const
	Returns the property named key if this var is an object.
int	length () const
	Returns the length of this var if it is an array or a dic.
bool	operator== (const Var &other) const
	Evaluates equality of type and value of two vars.
bool	is (Type t) const
	Checks if this var's type is t.
bool	isArrayOf (Type t) const
	Returns true if this var is an array and all its items have type t
bool	isArrayOf (int n, Type t) const
	Returns true if this var is an array of n items and all its items have type t
bool	is (const char *clas) const
	Checks if this var is an object of class clas.
bool	has (const String &k) const
	Checks if this var is an object and has a property named k.
bool	has (const String &k, Type t) const
	Checks if this var is an object and has a property named k of type t.
bool	contains (const Var &x) const
	Checks if this var is an array and contains an element with value x.
void	clear ()
	Clears the contents if this var is an array or an object.
void	remove (const String &k)
	Removes the property named k, if this var is an object.
void	removeAt (int i, int n=1)
	Removes one or more items, starting at the given index, if this is an array.
Var	clone () const
	Returns an independent copy of this Var (for arrays and objects)
const Enumerator	all () const
	Returns an enumerator for this var's contents.

Static Public Member Functions
static Var	array (std::initializer_list< Var > b)
	Constructs an array with an initializer list.

---

The documentation for this class was generated from the following file:

• Var.h