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