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
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 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);
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
288private:
289 //==============================================================================
290 class VariantType;
291 class VariantType_Void;
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. */
331JUCE_API bool operator== (const var&, const var&);
332/** Compares the values of two var objects, using the var::equals() comparison. */
333JUCE_API bool operator!= (const var&, const var&);
334/** Compares the values of two var objects, using the var::equals() comparison. */
335JUCE_API bool operator< (const var&, const var&);
336/** Compares the values of two var objects, using the var::equals() comparison. */
337JUCE_API bool operator<= (const var&, const var&);
338/** Compares the values of two var objects, using the var::equals() comparison. */
339JUCE_API bool operator> (const var&, const var&);
340/** Compares the values of two var objects, using the var::equals() comparison. */
341JUCE_API bool operator>= (const var&, const var&);
342
343JUCE_API bool operator== (const var&, const String&);
344JUCE_API bool operator!= (const var&, const String&);
345JUCE_API bool operator== (const var&, const char*);
346JUCE_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*/
353template <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
361template <>
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