juce/source/src/containers/juce_Variant.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_VARIANT_JUCEHEADER__
  27 #define __JUCE_VARIANT_JUCEHEADER__
  28
  29 #include "../text/juce_Identifier.h"
  30 #include "../io/streams/juce_OutputStream.h"
  31 #include "../io/streams/juce_InputStream.h"
  32 #include "../containers/juce_Array.h"
  33
  34 #ifndef DOXYGEN
  35  class ReferenceCountedObject;
  36  class DynamicObject;
  37 #endif
  38
  39 //==============================================================================
  40 /**
  41     A variant class, that can be used to hold a range of primitive values.
  42
  43     A var object can hold a range of simple primitive values, strings, or
  44     any kind of ReferenceCountedObject. The var class is intended to act like
  45     the kind of values used in dynamic scripting languages.
  46
  47     You can save/load var objects either in a small, proprietary binary format
  48     using writeToStream()/readFromStream(), or as JSON by using the JSON class.
  49
  50     @see JSON, DynamicObject
  51 */
  52 class JUCE_API  var
  53 {
  54 public:
  55     //==============================================================================
  56     typedef const var (DynamicObject::*MethodFunction) (const var* arguments, int numArguments);
  57     typedef Identifier identifier;
  58
  59     //==============================================================================
  60     /** Creates a void variant. */
  61     var() noexcept;
  62
  63     /** Destructor. */
  64     ~var() noexcept;
  65
  66     /** A static var object that can be used where you need an empty variant object. */
  67     static const var null;
  68
  69     var (const var& valueToCopy);
  70     var (int value) noexcept;
  71     var (int64 value) noexcept;
  72     var (bool value) noexcept;
  73     var (double value) noexcept;
  74     var (const char* value);
  75     var (const wchar_t* value);
  76     var (const String& value);
  77     var (const Array<var>& value);
  78     var (ReferenceCountedObject* object);
  79     var (MethodFunction method) noexcept;
  80
  81     const var& operator= (const var& valueToCopy);
  82     const var& operator= (int value);
  83     const var& operator= (int64 value);
  84     const var& operator= (bool value);
  85     const var& operator= (double value);
  86     const var& operator= (const char* value);
  87     const var& operator= (const wchar_t* value);
  88     const var& operator= (const String& value);
  89     const var& operator= (const Array<var>& value);
  90     const var& operator= (ReferenceCountedObject* object);
  91     const var& operator= (MethodFunction method);
  92
  93     void swapWith (var& other) noexcept;
  94
  95     operator int() const noexcept;
  96     operator int64() const noexcept;
  97     operator bool() const noexcept;
  98     operator float() const noexcept;
  99     operator double() const noexcept;
 100     operator String() const;
 101     String toString() const;
 102     Array<var>* getArray() const noexcept;
 103     ReferenceCountedObject* getObject() const noexcept;
 104     DynamicObject* getDynamicObject() const noexcept;
 105
 106     bool isVoid() const noexcept;
 107     bool isInt() const noexcept;
 108     bool isInt64() const noexcept;
 109     bool isBool() const noexcept;
 110     bool isDouble() const noexcept;
 111     bool isString() const noexcept;
 112     bool isObject() const noexcept;
 113     bool isArray() const noexcept;
 114     bool isMethod() const noexcept;
 115
 116     /** Returns true if this var has the same value as the one supplied.
 117         Note that this ignores the type, so a string var "123" and an integer var with the
 118         value 123 are considered to be equal.
 119         @see equalsWithSameType
 120     */
 121     bool equals (const var& other) const noexcept;
 122
 123     /** Returns true if this var has the same value and type as the one supplied.
 124         This differs from equals() because e.g. "123" and 123 will be considered different.
 125         @see equals
 126     */
 127     bool equalsWithSameType (const var& other) const noexcept;
 128
 129     //==============================================================================
 130     /** If the var is an array, this returns the number of elements.
 131         If the var isn't actually an array, this will return 0.
 132     */
 133     int size() const;
 134
 135     /** If the var is an array, this can be used to return one of its elements.
 136         To call this method, you must make sure that the var is actually an array, and
 137         that the index is a valid number. If these conditions aren't met, behaviour is
 138         undefined.
 139         For more control over the array's contents, you can call getArray() and manipulate
 140         it directly as an Array\<var\>.
 141     */
 142     const var& operator[] (int arrayIndex) const;
 143
 144     /** If the var is an array, this can be used to return one of its elements.
 145         To call this method, you must make sure that the var is actually an array, and
 146         that the index is a valid number. If these conditions aren't met, behaviour is
 147         undefined.
 148         For more control over the array's contents, you can call getArray() and manipulate
 149         it directly as an Array\<var\>.
 150     */
 151     var& operator[] (int arrayIndex);
 152
 153     /** Appends an element to the var, converting it to an array if it isn't already one.
 154         If the var isn't an array, it will be converted to one, and if its value was non-void,
 155         this value will be kept as the first element of the new array. The parameter value
 156         will then be appended to it.
 157         For more control over the array's contents, you can call getArray() and manipulate
 158         it directly as an Array\<var\>.
 159     */
 160     void append (const var& valueToAppend);
 161
 162     /** Inserts an element to the var, converting it to an array if it isn't already one.
 163         If the var isn't an array, it will be converted to one, and if its value was non-void,
 164         this value will be kept as the first element of the new array. The parameter value
 165         will then be inserted into it.
 166         For more control over the array's contents, you can call getArray() and manipulate
 167         it directly as an Array\<var\>.
 168     */
 169     void insert (int index, const var& value);
 170
 171     /** If the var is an array, this removes one of its elements.
 172         If the index is out-of-range or the var isn't an array, nothing will be done.
 173         For more control over the array's contents, you can call getArray() and manipulate
 174         it directly as an Array\<var\>.
 175     */
 176     void remove (int index);
 177
 178     /** Treating the var as an array, this resizes it to contain the specified number of elements.
 179         If the var isn't an array, it will be converted to one, and if its value was non-void,
 180         this value will be kept as the first element of the new array before resizing.
 181         For more control over the array's contents, you can call getArray() and manipulate
 182         it directly as an Array\<var\>.
 183     */
 184     void resize (int numArrayElementsWanted);
 185
 186     /** If the var is an array, this searches it for the first occurrence of the specified value,
 187         and returns its index.
 188         If the var isn't an array, or if the value isn't found, this returns -1.
 189     */
 190     int indexOf (const var& value) const;
 191
 192     //==============================================================================
 193     /** If this variant is an object, this returns one of its properties. */
 194     var operator[] (const Identifier& propertyName) const;
 195
 196     /** If this variant is an object, this invokes one of its methods with no arguments. */
 197     var call (const Identifier& method) const;
 198     /** If this variant is an object, this invokes one of its methods with one argument. */
 199     var call (const Identifier& method, const var& arg1) const;
 200     /** If this variant is an object, this invokes one of its methods with 2 arguments. */
 201     var call (const Identifier& method, const var& arg1, const var& arg2) const;
 202     /** If this variant is an object, this invokes one of its methods with 3 arguments. */
 203     var call (const Identifier& method, const var& arg1, const var& arg2, const var& arg3);
 204     /** If this variant is an object, this invokes one of its methods with 4 arguments. */
 205     var call (const Identifier& method, const var& arg1, const var& arg2, const var& arg3, const var& arg4) const;
 206     /** If this variant is an object, this invokes one of its methods with 5 arguments. */
 207     var call (const Identifier& method, const var& arg1, const var& arg2, const var& arg3, const var& arg4, const var& arg5) const;
 208     /** If this variant is an object, this invokes one of its methods with a list of arguments. */
 209     var invoke (const Identifier& method, const var* arguments, int numArguments) const;
 210
 211     //==============================================================================
 212     /** Writes a binary representation of this value to a stream.
 213         The data can be read back later using readFromStream().
 214         @see JSON
 215     */
 216     void writeToStream (OutputStream& output) const;
 217
 218     /** Reads back a stored binary representation of a value.
 219         The data in the stream must have been written using writeToStream(), or this
 220         will have unpredictable results.
 221         @see JSON
 222     */
 223     static var readFromStream (InputStream& input);
 224
 225 private:
 226     //==============================================================================
 227     class VariantType;         friend class VariantType;
 228     class VariantType_Void;    friend class VariantType_Void;
 229     class VariantType_Int;     friend class VariantType_Int;
 230     class VariantType_Int64;   friend class VariantType_Int64;
 231     class VariantType_Double;  friend class VariantType_Double;
 232     class VariantType_Bool;    friend class VariantType_Bool;
 233     class VariantType_String;  friend class VariantType_String;
 234     class VariantType_Object;  friend class VariantType_Object;
 235     class VariantType_Array;   friend class VariantType_Array;
 236     class VariantType_Method;  friend class VariantType_Method;
 237
 238     union ValueUnion
 239     {
 240         int intValue;
 241         int64 int64Value;
 242         bool boolValue;
 243         double doubleValue;
 244         char stringValue [sizeof (String)];
 245         ReferenceCountedObject* objectValue;
 246         Array<var>* arrayValue;
 247         MethodFunction methodValue;
 248     };
 249
 250     const VariantType* type;
 251     ValueUnion value;
 252
 253     Array<var>* convertToArray();
 254     friend class DynamicObject;
 255     var invokeMethod (DynamicObject*, const var*, int) const;
 256 };
 257
 258 /** Compares the values of two var objects, using the var::equals() comparison. */
 259 bool operator== (const var& v1, const var& v2) noexcept;
 260 /** Compares the values of two var objects, using the var::equals() comparison. */
 261 bool operator!= (const var& v1, const var& v2) noexcept;
 262 bool operator== (const var& v1, const String& v2);
 263 bool operator!= (const var& v1, const String& v2);
 264 bool operator== (const var& v1, const char* v2);
 265 bool operator!= (const var& v1, const char* v2);
 266
 267
 268 #endif   // __JUCE_VARIANT_JUCEHEADER__