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
27namespace 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{
47public:
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);
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
291private:
292 //==============================================================================
293 class VariantType;
294 class VariantType_Void;
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. */
332JUCE_API bool operator== (const var&, const var&);
333/** Compares the values of two var objects, using the var::equals() comparison. */
334JUCE_API bool operator!= (const var&, const var&);
335/** Compares the values of two var objects, using the var::equals() comparison. */
336JUCE_API bool operator< (const var&, const var&);
337/** Compares the values of two var objects, using the var::equals() comparison. */
338JUCE_API bool operator<= (const var&, const var&);
339/** Compares the values of two var objects, using the var::equals() comparison. */
340JUCE_API bool operator> (const var&, const var&);
341/** Compares the values of two var objects, using the var::equals() comparison. */
342JUCE_API bool operator>= (const var&, const var&);
343
344JUCE_API bool operator== (const var&, const String&);
345JUCE_API bool operator!= (const var&, const String&);
346JUCE_API bool operator== (const var&, const char*);
347JUCE_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*/
354template <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
362template <>
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/** @}*/
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.
#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.
This structure is passed to a NativeFunction callback, and contains invocation details about the func...