JUCE  v6.1.6 (6.0.8-1114)
JUCE API
Looking for a senior C++ dev?
I'm looking for work. Hire me!
juce::var Class Reference

A variant class, that can be used to hold a range of primitive values. More...

#include <juce_Variant.h>

Collaboration diagram for juce::var:

Classes

struct  NativeFunctionArgs
 This structure is passed to a NativeFunction callback, and contains invocation details about the function's arguments and context. More...
 
union  ValueUnion
 

Public Types

using NativeFunction = std::function< var(const NativeFunctionArgs &)>
 

Public Member Functions

 var () noexcept
 Creates a void variant. More...
 
 var (Array< var > &&)
 
 var (bool value) noexcept
 
 var (const Array< var > &value)
 
 var (const char *value)
 
 var (const MemoryBlock &binaryData)
 
 var (const String &value)
 
 var (const StringArray &value)
 
 var (const var &valueToCopy)
 
 var (const void *binaryData, size_t dataSize)
 
 var (const wchar_t *value)
 
 var (double value) noexcept
 
 var (int value) noexcept
 
 var (int64 value) noexcept
 
 var (MemoryBlock &&)
 
 var (NativeFunction method) noexcept
 
 var (ReferenceCountedObject *object)
 
 var (String &&)
 
 var (var &&) noexcept
 
 ~var () noexcept
 Destructor. More...
 
void append (const var &valueToAppend)
 Appends an element to the var, converting it to an array if it isn't already one. More...
 
var call (const Identifier &method) const
 Invokes a named method call with no arguments. More...
 
var call (const Identifier &method, const var &arg1) const
 Invokes a named method call with one argument. More...
 
var call (const Identifier &method, const var &arg1, const var &arg2) const
 Invokes a named method call with 2 arguments. More...
 
var call (const Identifier &method, const var &arg1, const var &arg2, const var &arg3)
 Invokes a named method call with 3 arguments. More...
 
var call (const Identifier &method, const var &arg1, const var &arg2, const var &arg3, const var &arg4) const
 Invokes a named method call with 4 arguments. More...
 
var call (const Identifier &method, const var &arg1, const var &arg2, const var &arg3, const var &arg4, const var &arg5) const
 Invokes a named method call with 5 arguments. More...
 
var clone () const noexcept
 Returns a deep copy of this object. More...
 
bool equals (const var &other) const noexcept
 Returns true if this var has the same value as the one supplied. More...
 
bool equalsWithSameType (const var &other) const noexcept
 Returns true if this var has the same value and type as the one supplied. More...
 
Array< var > * getArray () const noexcept
 If this variant holds an array, this provides access to it. More...
 
MemoryBlockgetBinaryData () const noexcept
 If this variant holds a memory block, this provides access to it. More...
 
DynamicObjectgetDynamicObject () const noexcept
 
NativeFunction getNativeFunction () const
 If this object is a method, this returns the function pointer. More...
 
ReferenceCountedObjectgetObject () const noexcept
 
var getProperty (const Identifier &propertyName, const var &defaultReturnValue) const
 If this variant is an object, this returns one of its properties, or a default fallback value if the property is not set. More...
 
bool hasProperty (const Identifier &propertyName) const noexcept
 Returns true if this variant is an object and if it has the given property. More...
 
bool hasSameTypeAs (const var &other) const noexcept
 Returns true if this var has the same type as the one supplied. More...
 
int indexOf (const var &value) const
 If the var is an array, this searches it for the first occurrence of the specified value, and returns its index. More...
 
void insert (int index, const var &value)
 Inserts an element to the var, converting it to an array if it isn't already one. More...
 
var invoke (const Identifier &method, const var *arguments, int numArguments) const
 Invokes a named method call with a list of arguments. More...
 
bool isArray () const noexcept
 
bool isBinaryData () const noexcept
 
bool isBool () const noexcept
 
bool isDouble () const noexcept
 
bool isInt () const noexcept
 
bool isInt64 () const noexcept
 
bool isMethod () const noexcept
 
bool isObject () const noexcept
 
bool isString () const noexcept
 
bool isUndefined () const noexcept
 
bool isVoid () const noexcept
 
 operator bool () const noexcept
 
 operator double () const noexcept
 
 operator float () const noexcept
 
 operator int () const noexcept
 
 operator int64 () const noexcept
 
 operator String () const
 
varoperator= (bool value)
 
varoperator= (const Array< var > &value)
 
varoperator= (const char *value)
 
varoperator= (const MemoryBlock &value)
 
varoperator= (const String &value)
 
varoperator= (const var &valueToCopy)
 
varoperator= (const wchar_t *value)
 
varoperator= (double value)
 
varoperator= (int value)
 
varoperator= (int64 value)
 
varoperator= (NativeFunction method)
 
varoperator= (ReferenceCountedObject *object)
 
varoperator= (String &&)
 
varoperator= (var &&) noexcept
 
const varoperator[] (const char *propertyName) const
 If this variant is an object, this returns one of its properties. More...
 
const varoperator[] (const Identifier &propertyName) const
 If this variant is an object, this returns one of its properties. More...
 
varoperator[] (int arrayIndex)
 If the var is an array, this can be used to return one of its elements. More...
 
const varoperator[] (int arrayIndex) const
 If the var is an array, this can be used to return one of its elements. More...
 
void remove (int index)
 If the var is an array, this removes one of its elements. More...
 
void resize (int numArrayElementsWanted)
 Treating the var as an array, this resizes it to contain the specified number of elements. More...
 
int size () const
 If the var is an array, this returns the number of elements. More...
 
void swapWith (var &other) noexcept
 
String toString () const
 
void writeToStream (OutputStream &output) const
 Writes a binary representation of this value to a stream. More...
 

Static Public Member Functions

static var readFromStream (InputStream &input)
 Reads back a stored binary representation of a value. More...
 
static var undefined () noexcept
 Returns a var object that can be used where you need the javascript "undefined" value. More...
 

Private Member Functions

 var (const ReferenceCountedObject *)=delete
 
 var (const VariantType &) noexcept
 
 var (const void *)=delete
 
Array< var > * convertToArray ()
 
varoperator= (const ReferenceCountedObject *)=delete
 
varoperator= (const void *)=delete
 

Private Attributes

const VariantType * type
 
ValueUnion value
 

Friends

bool canCompare (const var &, const var &)
 

Detailed Description

A variant class, that can be used to hold a range of primitive values.

A var object can hold a range of simple primitive values, strings, or any kind of ReferenceCountedObject. The var class is intended to act like the kind of values used in dynamic scripting languages.

You can save/load var objects either in a small, proprietary binary format using writeToStream()/readFromStream(), or as JSON by using the JSON class.

See also
JSON, DynamicObject

@tags{Core}

Member Typedef Documentation

◆ NativeFunction

using juce::var::NativeFunction = std::function<var (const NativeFunctionArgs&)>

Constructor & Destructor Documentation

◆ var() [1/22]

juce::var::var ( )
noexcept

Creates a void variant.

◆ ~var()

juce::var::~var ( )
noexcept

Destructor.

◆ var() [2/22]

juce::var::var ( const var valueToCopy)

◆ var() [3/22]

juce::var::var ( int  value)
noexcept

◆ var() [4/22]

juce::var::var ( int64  value)
noexcept

◆ var() [5/22]

juce::var::var ( bool  value)
noexcept

◆ var() [6/22]

juce::var::var ( double  value)
noexcept

◆ var() [7/22]

juce::var::var ( const char *  value)

◆ var() [8/22]

juce::var::var ( const wchar_t *  value)

◆ var() [9/22]

juce::var::var ( const String value)

◆ var() [10/22]

juce::var::var ( const Array< var > &  value)

◆ var() [11/22]

juce::var::var ( const StringArray value)

◆ var() [12/22]

juce::var::var ( ReferenceCountedObject object)

◆ var() [13/22]

juce::var::var ( NativeFunction  method)
noexcept

◆ var() [14/22]

juce::var::var ( const void *  binaryData,
size_t  dataSize 
)

◆ var() [15/22]

juce::var::var ( const MemoryBlock binaryData)

◆ var() [16/22]

juce::var::var ( var &&  )
noexcept

◆ var() [17/22]

juce::var::var ( String &&  )

◆ var() [18/22]

juce::var::var ( MemoryBlock &&  )

◆ var() [19/22]

juce::var::var ( Array< var > &&  )

◆ var() [20/22]

juce::var::var ( const VariantType &  )
privatenoexcept

◆ var() [21/22]

juce::var::var ( const ReferenceCountedObject )
privatedelete

◆ var() [22/22]

juce::var::var ( const void *  )
privatedelete

Member Function Documentation

◆ append()

void juce::var::append ( const var valueToAppend)

Appends an element to the var, converting it to an array if it isn't already one.

If the var isn't an array, it will be converted to one, and if its value was non-void, this value will be kept as the first element of the new array. The parameter value will then be appended to it. For more control over the array's contents, you can call getArray() and manipulate it directly as an Array<var>.

◆ call() [1/6]

var juce::var::call ( const Identifier method) const

Invokes a named method call with no arguments.

◆ call() [2/6]

var juce::var::call ( const Identifier method,
const var arg1 
) const

Invokes a named method call with one argument.

◆ call() [3/6]

var juce::var::call ( const Identifier method,
const var arg1,
const var arg2 
) const

Invokes a named method call with 2 arguments.

◆ call() [4/6]

var juce::var::call ( const Identifier method,
const var arg1,
const var arg2,
const var arg3 
)

Invokes a named method call with 3 arguments.

◆ call() [5/6]

var juce::var::call ( const Identifier method,
const var arg1,
const var arg2,
const var arg3,
const var arg4 
) const

Invokes a named method call with 4 arguments.

◆ call() [6/6]

var juce::var::call ( const Identifier method,
const var arg1,
const var arg2,
const var arg3,
const var arg4,
const var arg5 
) const

Invokes a named method call with 5 arguments.

◆ clone()

var juce::var::clone ( ) const
noexcept

Returns a deep copy of this object.

For simple types this just returns a copy, but if the object contains any arrays or DynamicObjects, they will be cloned (recursively).

◆ convertToArray()

Array<var>* juce::var::convertToArray ( )
private

◆ equals()

bool juce::var::equals ( const var other) const
noexcept

Returns true if this var has the same value as the one supplied.

Note that this ignores the type, so a string var "123" and an integer var with the value 123 are considered to be equal.

Note that equality checking depends on the "wrapped" type of the object on which equals() is called. That means the following code will convert the right-hand-side argument to a string and compare the string values, because the object on the left-hand-side was initialised from a string:

var ("123").equals (var (123))

However, the following code will convert the right-hand-side argument to a double and compare the values as doubles, because the object on the left-hand-side was initialised from a double:

var (45.6).equals ("45.6000")
See also
equalsWithSameType

◆ equalsWithSameType()

bool juce::var::equalsWithSameType ( const var other) const
noexcept

Returns true if this var has the same value and type as the one supplied.

This differs from equals() because e.g. "123" and 123 will be considered different.

See also
equals

Referenced by juce::ValueTreePropertyWithDefault::SynchronousValueSource::setValue().

◆ getArray()

Array<var>* juce::var::getArray ( ) const
noexcept

If this variant holds an array, this provides access to it.

NOTE: Beware when you use this - the array pointer is only valid for the lifetime of the variant that returned it, so be very careful not to call this method on temporary var objects that are the return-value of a function, and which may go out of scope before you use the array!

Referenced by juce::ValueTreePropertyWithDefault::setValue(), and juce::varArrayToNSArray().

◆ getBinaryData()

MemoryBlock* juce::var::getBinaryData ( ) const
noexcept

If this variant holds a memory block, this provides access to it.

NOTE: Beware when you use this - the MemoryBlock pointer is only valid for the lifetime of the variant that returned it, so be very careful not to call this method on temporary var objects that are the return-value of a function, and which may go out of scope before you use the MemoryBlock!

◆ getDynamicObject()

DynamicObject* juce::var::getDynamicObject ( ) const
noexcept

◆ getNativeFunction()

NativeFunction juce::var::getNativeFunction ( ) const

If this object is a method, this returns the function pointer.

◆ getObject()

ReferenceCountedObject* juce::var::getObject ( ) const
noexcept

◆ getProperty()

var juce::var::getProperty ( const Identifier propertyName,
const var defaultReturnValue 
) const

If this variant is an object, this returns one of its properties, or a default fallback value if the property is not set.

◆ hasProperty()

bool juce::var::hasProperty ( const Identifier propertyName) const
noexcept

Returns true if this variant is an object and if it has the given property.

◆ hasSameTypeAs()

bool juce::var::hasSameTypeAs ( const var other) const
noexcept

Returns true if this var has the same type as the one supplied.

◆ indexOf()

int juce::var::indexOf ( const var value) const

If the var is an array, this searches it for the first occurrence of the specified value, and returns its index.

If the var isn't an array, or if the value isn't found, this returns -1.

◆ insert()

void juce::var::insert ( int  index,
const var value 
)

Inserts an element to the var, converting it to an array if it isn't already one.

If the var isn't an array, it will be converted to one, and if its value was non-void, this value will be kept as the first element of the new array. The parameter value will then be inserted into it. For more control over the array's contents, you can call getArray() and manipulate it directly as an Array<var>.

◆ invoke()

var juce::var::invoke ( const Identifier method,
const var arguments,
int  numArguments 
) const

Invokes a named method call with a list of arguments.

◆ isArray()

bool juce::var::isArray ( ) const
noexcept

◆ isBinaryData()

bool juce::var::isBinaryData ( ) const
noexcept

◆ isBool()

bool juce::var::isBool ( ) const
noexcept

◆ isDouble()

bool juce::var::isDouble ( ) const
noexcept

◆ isInt()

bool juce::var::isInt ( ) const
noexcept

◆ isInt64()

bool juce::var::isInt64 ( ) const
noexcept

◆ isMethod()

bool juce::var::isMethod ( ) const
noexcept

◆ isObject()

bool juce::var::isObject ( ) const
noexcept

◆ isString()

bool juce::var::isString ( ) const
noexcept

◆ isUndefined()

bool juce::var::isUndefined ( ) const
noexcept

◆ isVoid()

bool juce::var::isVoid ( ) const
noexcept

◆ operator bool()

juce::var::operator bool ( ) const
noexcept

◆ operator double()

juce::var::operator double ( ) const
noexcept

◆ operator float()

juce::var::operator float ( ) const
noexcept

◆ operator int()

juce::var::operator int ( ) const
noexcept

◆ operator int64()

juce::var::operator int64 ( ) const
noexcept

◆ operator String()

juce::var::operator String ( ) const

◆ operator=() [1/16]

var& juce::var::operator= ( bool  value)

◆ operator=() [2/16]

var& juce::var::operator= ( const Array< var > &  value)

◆ operator=() [3/16]

var& juce::var::operator= ( const char *  value)

◆ operator=() [4/16]

var& juce::var::operator= ( const MemoryBlock value)

◆ operator=() [5/16]

var& juce::var::operator= ( const ReferenceCountedObject )
privatedelete

◆ operator=() [6/16]

var& juce::var::operator= ( const String value)

◆ operator=() [7/16]

var& juce::var::operator= ( const var valueToCopy)

◆ operator=() [8/16]

var& juce::var::operator= ( const void *  )
privatedelete

◆ operator=() [9/16]

var& juce::var::operator= ( const wchar_t *  value)

◆ operator=() [10/16]

var& juce::var::operator= ( double  value)

◆ operator=() [11/16]

var& juce::var::operator= ( int  value)

◆ operator=() [12/16]

var& juce::var::operator= ( int64  value)

◆ operator=() [13/16]

var& juce::var::operator= ( NativeFunction  method)

◆ operator=() [14/16]

var& juce::var::operator= ( ReferenceCountedObject object)

◆ operator=() [15/16]

var& juce::var::operator= ( String &&  )

◆ operator=() [16/16]

var& juce::var::operator= ( var &&  )
noexcept

◆ operator[]() [1/4]

const var& juce::var::operator[] ( const char *  propertyName) const

If this variant is an object, this returns one of its properties.

◆ operator[]() [2/4]

const var& juce::var::operator[] ( const Identifier propertyName) const

If this variant is an object, this returns one of its properties.

◆ operator[]() [3/4]

var& juce::var::operator[] ( int  arrayIndex)

If the var is an array, this can be used to return one of its elements.

To call this method, you must make sure that the var is actually an array, and that the index is a valid number. If these conditions aren't met, behaviour is undefined. For more control over the array's contents, you can call getArray() and manipulate it directly as an Array<var>.

◆ operator[]() [4/4]

const var& juce::var::operator[] ( int  arrayIndex) const

If the var is an array, this can be used to return one of its elements.

To call this method, you must make sure that the var is actually an array, and that the index is a valid number. If these conditions aren't met, behaviour is undefined. For more control over the array's contents, you can call getArray() and manipulate it directly as an Array<var>.

◆ readFromStream()

static var juce::var::readFromStream ( InputStream input)
static

Reads back a stored binary representation of a value.

The data in the stream must have been written using writeToStream(), or this will have unpredictable results.

See also
JSON

◆ remove()

void juce::var::remove ( int  index)

If the var is an array, this removes one of its elements.

If the index is out-of-range or the var isn't an array, nothing will be done. For more control over the array's contents, you can call getArray() and manipulate it directly as an Array<var>.

◆ resize()

void juce::var::resize ( int  numArrayElementsWanted)

Treating the var as an array, this resizes it to contain the specified number of elements.

If the var isn't an array, it will be converted to one, and if its value was non-void, this value will be kept as the first element of the new array before resizing. For more control over the array's contents, you can call getArray() and manipulate it directly as an Array<var>.

◆ size()

int juce::var::size ( ) const

If the var is an array, this returns the number of elements.

If the var isn't actually an array, this will return 0.

◆ swapWith()

void juce::var::swapWith ( var other)
noexcept

◆ toString()

String juce::var::toString ( ) const

◆ undefined()

static var juce::var::undefined ( )
staticnoexcept

Returns a var object that can be used where you need the javascript "undefined" value.

◆ writeToStream()

void juce::var::writeToStream ( OutputStream output) const

Writes a binary representation of this value to a stream.

The data can be read back later using readFromStream().

See also
JSON

Friends And Related Function Documentation

◆ canCompare

bool canCompare ( const var ,
const var  
)
friend

Member Data Documentation

◆ type

const VariantType* juce::var::type
private

◆ value

ValueUnion juce::var::value
private

The documentation for this class was generated from the following file:
juce::var::var
var() noexcept
Creates a void variant.