OpenShot Library | OpenShotAudio  0.2.2
juce_Variant.h
1 
2 /** @weakgroup juce_core-containers
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  A variant class, that can be used to hold a range of primitive values.
33 
34  A var object can hold a range of simple primitive values, strings, or
35  any kind of ReferenceCountedObject. The var class is intended to act like
36  the kind of values used in dynamic scripting languages.
37 
38  You can save/load var objects either in a small, proprietary binary format
39  using writeToStream()/readFromStream(), or as JSON by using the JSON class.
40 
41  @see JSON, DynamicObject
42 
43  @tags{Core}
44 */
46 {
47 public:
48  //==============================================================================
49  /** This structure is passed to a NativeFunction callback, and contains invocation
50  details about the function's arguments and context.
51  */
53  {
54  NativeFunctionArgs (const var& thisObject, const var* args, int numArgs) noexcept;
55 
56  const var& thisObject;
57  const var* arguments;
58  int numArguments;
59  };
60 
61  using NativeFunction = std::function<var(const NativeFunctionArgs&)>;
62 
63  //==============================================================================
64  /** Creates a void variant. */
65  var() noexcept;
66 
67  /** Destructor. */
68  ~var() noexcept;
69 
70  var (const var& valueToCopy);
71  var (int value) noexcept;
72  var (int64 value) noexcept;
73  var (bool value) noexcept;
74  var (double value) noexcept;
75  var (const char* value);
76  var (const wchar_t* value);
77  var (const String& value);
78  var (const Array<var>& value);
79  var (const StringArray& value);
80  var (ReferenceCountedObject* object);
81  var (NativeFunction method) noexcept;
82  var (const void* binaryData, size_t dataSize);
83  var (const MemoryBlock& binaryData);
84 
85  var& operator= (const var& valueToCopy);
86  var& operator= (int value);
87  var& operator= (int64 value);
88  var& operator= (bool value);
89  var& operator= (double value);
90  var& operator= (const char* value);
91  var& operator= (const wchar_t* value);
92  var& operator= (const String& value);
93  var& operator= (const MemoryBlock& value);
94  var& operator= (const Array<var>& value);
95  var& operator= (ReferenceCountedObject* object);
96  var& operator= (NativeFunction method);
97 
98  var (var&&) noexcept;
99  var (String&&);
100  var (MemoryBlock&&);
101  var (Array<var>&&);
102  var& operator= (var&&) noexcept;
103  var& operator= (String&&);
104 
105  void swapWith (var& other) noexcept;
106 
107  /** Returns a var object that can be used where you need the javascript "undefined" value. */
108  static var undefined() noexcept;
109 
110  //==============================================================================
111  operator int() const noexcept;
112  operator int64() const noexcept;
113  operator bool() const noexcept;
114  operator float() const noexcept;
115  operator double() const noexcept;
116  operator String() const;
117  String toString() const;
118 
119  /** If this variant holds an array, this provides access to it.
120  NOTE: Beware when you use this - the array pointer is only valid for the lifetime
121  of the variant that returned it, so be very careful not to call this method on temporary
122  var objects that are the return-value of a function, and which may go out of scope before
123  you use the array!
124  */
125  Array<var>* getArray() const noexcept;
126 
127  /** If this variant holds a memory block, this provides access to it.
128  NOTE: Beware when you use this - the MemoryBlock pointer is only valid for the lifetime
129  of the variant that returned it, so be very careful not to call this method on temporary
130  var objects that are the return-value of a function, and which may go out of scope before
131  you use the MemoryBlock!
132  */
133  MemoryBlock* getBinaryData() const noexcept;
134 
135  ReferenceCountedObject* getObject() const noexcept;
136  DynamicObject* getDynamicObject() const noexcept;
137 
138  //==============================================================================
139  bool isVoid() const noexcept;
140  bool isUndefined() const noexcept;
141  bool isInt() const noexcept;
142  bool isInt64() const noexcept;
143  bool isBool() const noexcept;
144  bool isDouble() const noexcept;
145  bool isString() const noexcept;
146  bool isObject() const noexcept;
147  bool isArray() const noexcept;
148  bool isBinaryData() const noexcept;
149  bool isMethod() const noexcept;
150 
151  /** Returns true if this var has the same value as the one supplied.
152  Note that this ignores the type, so a string var "123" and an integer var with the
153  value 123 are considered to be equal.
154  @see equalsWithSameType
155  */
156  bool equals (const var& other) const noexcept;
157 
158  /** Returns true if this var has the same value and type as the one supplied.
159  This differs from equals() because e.g. "123" and 123 will be considered different.
160  @see equals
161  */
162  bool equalsWithSameType (const var& other) const noexcept;
163 
164  /** Returns true if this var has the same type as the one supplied. */
165  bool hasSameTypeAs (const var& other) const noexcept;
166 
167  /** Returns a deep copy of this object.
168  For simple types this just returns a copy, but if the object contains any arrays
169  or DynamicObjects, they will be cloned (recursively).
170  */
171  var clone() const noexcept;
172 
173  //==============================================================================
174  /** If the var is an array, this returns the number of elements.
175  If the var isn't actually an array, this will return 0.
176  */
177  int size() const;
178 
179  /** If the var is an array, this can be used to return one of its elements.
180  To call this method, you must make sure that the var is actually an array, and
181  that the index is a valid number. If these conditions aren't met, behaviour is
182  undefined.
183  For more control over the array's contents, you can call getArray() and manipulate
184  it directly as an Array<var>.
185  */
186  const var& operator[] (int arrayIndex) const;
187 
188  /** If the var is an array, this can be used to return one of its elements.
189  To call this method, you must make sure that the var is actually an array, and
190  that the index is a valid number. If these conditions aren't met, behaviour is
191  undefined.
192  For more control over the array's contents, you can call getArray() and manipulate
193  it directly as an Array<var>.
194  */
195  var& operator[] (int arrayIndex);
196 
197  /** Appends an element to the var, converting it to an array if it isn't already one.
198  If the var isn't an array, it will be converted to one, and if its value was non-void,
199  this value will be kept as the first element of the new array. The parameter value
200  will then be appended to it.
201  For more control over the array's contents, you can call getArray() and manipulate
202  it directly as an Array<var>.
203  */
204  void append (const var& valueToAppend);
205 
206  /** Inserts an element to the var, converting it to an array if it isn't already one.
207  If the var isn't an array, it will be converted to one, and if its value was non-void,
208  this value will be kept as the first element of the new array. The parameter value
209  will then be inserted into it.
210  For more control over the array's contents, you can call getArray() and manipulate
211  it directly as an Array<var>.
212  */
213  void insert (int index, const var& value);
214 
215  /** If the var is an array, this removes one of its elements.
216  If the index is out-of-range or the var isn't an array, nothing will be done.
217  For more control over the array's contents, you can call getArray() and manipulate
218  it directly as an Array<var>.
219  */
220  void remove (int index);
221 
222  /** Treating the var as an array, this resizes it to contain the specified number of elements.
223  If the var isn't an array, it will be converted to one, and if its value was non-void,
224  this value will be kept as the first element of the new array before resizing.
225  For more control over the array's contents, you can call getArray() and manipulate
226  it directly as an Array<var>.
227  */
228  void resize (int numArrayElementsWanted);
229 
230  /** If the var is an array, this searches it for the first occurrence of the specified value,
231  and returns its index.
232  If the var isn't an array, or if the value isn't found, this returns -1.
233  */
234  int indexOf (const var& value) const;
235 
236  //==============================================================================
237  /** If this variant is an object, this returns one of its properties. */
238  const var& operator[] (const Identifier& propertyName) const;
239  /** If this variant is an object, this returns one of its properties. */
240  const var& operator[] (const char* propertyName) const;
241  /** If this variant is an object, this returns one of its properties, or a default
242  fallback value if the property is not set. */
243  var getProperty (const Identifier& propertyName, const var& defaultReturnValue) const;
244  /** Returns true if this variant is an object and if it has the given property. */
245  bool hasProperty (const Identifier& propertyName) const noexcept;
246 
247  /** Invokes a named method call with no arguments. */
248  var call (const Identifier& method) const;
249  /** Invokes a named method call with one argument. */
250  var call (const Identifier& method, const var& arg1) const;
251  /** Invokes a named method call with 2 arguments. */
252  var call (const Identifier& method, const var& arg1, const var& arg2) const;
253  /** Invokes a named method call with 3 arguments. */
254  var call (const Identifier& method, const var& arg1, const var& arg2, const var& arg3);
255  /** Invokes a named method call with 4 arguments. */
256  var call (const Identifier& method, const var& arg1, const var& arg2, const var& arg3, const var& arg4) const;
257  /** Invokes a named method call with 5 arguments. */
258  var call (const Identifier& method, const var& arg1, const var& arg2, const var& arg3, const var& arg4, const var& arg5) const;
259  /** Invokes a named method call with a list of arguments. */
260  var invoke (const Identifier& method, const var* arguments, int numArguments) const;
261  /** If this object is a method, this returns the function pointer. */
262  NativeFunction getNativeFunction() const;
263 
264  //==============================================================================
265  /** Writes a binary representation of this value to a stream.
266  The data can be read back later using readFromStream().
267  @see JSON
268  */
269  void writeToStream (OutputStream& output) const;
270 
271  /** Reads back a stored binary representation of a value.
272  The data in the stream must have been written using writeToStream(), or this
273  will have unpredictable results.
274  @see JSON
275  */
276  static var readFromStream (InputStream& input);
277 
278  /* This was a static empty var object, but is now deprecated as it's too easy to accidentally
279  use it indirectly during a static constructor, leading to hard-to-find order-of-initialisation
280  problems.
281  @deprecated If you need a default-constructed var, just use var() or {}.
282  The only time you might miss having var::null available might be if you need to return an
283  empty var from a function by reference, but if you need to do that, it's easy enough to use
284  a function-local static var and return that, avoiding any order-of-initialisation issues.
285  */
286  JUCE_DEPRECATED_STATIC (static const var null;)
287 
288 private:
289  //==============================================================================
290  class VariantType;
291  class VariantType_Void;
292  class VariantType_Undefined;
293  class VariantType_Int;
294  class VariantType_Int64;
295  class VariantType_Double;
296  class VariantType_Bool;
297  class VariantType_String;
298  class VariantType_Object;
299  class VariantType_Array;
300  class VariantType_Binary;
301  class VariantType_Method;
302 
303  union ValueUnion
304  {
305  int intValue;
306  int64 int64Value;
307  bool boolValue;
308  double doubleValue;
309  char stringValue[sizeof (String)];
310  ReferenceCountedObject* objectValue;
311  MemoryBlock* binaryValue;
312  NativeFunction* methodValue;
313  };
314 
315  friend bool canCompare (const var&, const var&);
316 
317  const VariantType* type;
318  ValueUnion value;
319 
320  Array<var>* convertToArray();
321  var (const VariantType&) noexcept;
322 
323  // This is needed to prevent the wrong constructor/operator being called
324  var (const ReferenceCountedObject*) = delete;
325  var& operator= (const ReferenceCountedObject*) = delete;
326  var (const void*) = delete;
327  var& operator= (const void*) = delete;
328 };
329 
330 /** Compares the values of two var objects, using the var::equals() comparison. */
331 JUCE_API bool operator== (const var&, const var&);
332 /** Compares the values of two var objects, using the var::equals() comparison. */
333 JUCE_API bool operator!= (const var&, const var&);
334 /** Compares the values of two var objects, using the var::equals() comparison. */
335 JUCE_API bool operator< (const var&, const var&);
336 /** Compares the values of two var objects, using the var::equals() comparison. */
337 JUCE_API bool operator<= (const var&, const var&);
338 /** Compares the values of two var objects, using the var::equals() comparison. */
339 JUCE_API bool operator> (const var&, const var&);
340 /** Compares the values of two var objects, using the var::equals() comparison. */
341 JUCE_API bool operator>= (const var&, const var&);
342 
343 JUCE_API bool operator== (const var&, const String&);
344 JUCE_API bool operator!= (const var&, const String&);
345 JUCE_API bool operator== (const var&, const char*);
346 JUCE_API bool operator!= (const var&, const char*);
347 
348 //==============================================================================
349 /** This template-overloaded class can be used to convert between var and custom types.
350 
351  @tags{Core}
352 */
353 template <typename Type>
355 {
356  static Type fromVar (const var& v) { return static_cast<Type> (v); }
357  static var toVar (const Type& t) { return t; }
358 };
359 
360 #ifndef DOXYGEN
361 template <>
362 struct VariantConverter<String>
363 {
364  static String fromVar (const var& v) { return v.toString(); }
365  static var toVar (const String& s) { return s; }
366 };
367 #endif
368 
369 } // namespace juce
370 
371 /** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:60
Represents a dynamically implemented object.
Represents a string identifier, designed for accessing properties by name.
The base class for streams that read data.
A class to hold a resizable block of raw data.
The base class for streams that write data to some kind of destination.
A base class which provides methods for reference-counting.
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:43
A variant class, that can be used to hold a range of primitive values.
Definition: juce_Variant.h:46
#define JUCE_API
This macro is added to all JUCE public class declarations.
This template-overloaded class can be used to convert between var and custom types.
Definition: juce_Variant.h:355
This structure is passed to a NativeFunction callback, and contains invocation details about the func...
Definition: juce_Variant.h:53