a427d98b558fec94c3dbedeca3e7b016a94f21b1
[WebKit-https.git] / Source / JavaScriptCore / API / JSValueRef.h
1 /*
2  * Copyright (C) 2006 Apple Inc.  All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  *
13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
24  */
25
26 #ifndef JSValueRef_h
27 #define JSValueRef_h
28
29 #include <JavaScriptCore/JSBase.h>
30 #include <JavaScriptCore/WebKitAvailability.h>
31
32 #ifndef __cplusplus
33 #include <stdbool.h>
34 #endif
35
36 /*!
37 @enum JSType
38 @abstract     A constant identifying the type of a JSValue.
39 @constant     kJSTypeUndefined  The unique undefined value.
40 @constant     kJSTypeNull       The unique null value.
41 @constant     kJSTypeBoolean    A primitive boolean value, one of true or false.
42 @constant     kJSTypeNumber     A primitive number value.
43 @constant     kJSTypeString     A primitive string value.
44 @constant     kJSTypeObject     An object value (meaning that this JSValueRef is a JSObjectRef).
45 @constant     kJSTypeSymbol     A primitive symbol value.
46 */
47 typedef enum {
48     kJSTypeUndefined,
49     kJSTypeNull,
50     kJSTypeBoolean,
51     kJSTypeNumber,
52     kJSTypeString,
53     kJSTypeObject,
54     kJSTypeSymbol JSC_API_AVAILABLE(macosx(JSC_MAC_TBA), ios(JSC_IOS_TBA))
55 } JSType;
56
57 /*!
58  @enum JSTypedArrayType
59  @abstract     A constant identifying the Typed Array type of a JSObjectRef.
60  @constant     kJSTypedArrayTypeInt8Array            Int8Array
61  @constant     kJSTypedArrayTypeInt16Array           Int16Array
62  @constant     kJSTypedArrayTypeInt32Array           Int32Array
63  @constant     kJSTypedArrayTypeUint8Array           Uint8Array
64  @constant     kJSTypedArrayTypeUint8ClampedArray    Uint8ClampedArray
65  @constant     kJSTypedArrayTypeUint16Array          Uint16Array
66  @constant     kJSTypedArrayTypeUint32Array          Uint32Array
67  @constant     kJSTypedArrayTypeFloat32Array         Float32Array
68  @constant     kJSTypedArrayTypeFloat64Array         Float64Array
69  @constant     kJSTypedArrayTypeArrayBuffer          ArrayBuffer
70  @constant     kJSTypedArrayTypeNone                 Not a Typed Array
71
72  */
73 typedef enum {
74     kJSTypedArrayTypeInt8Array,
75     kJSTypedArrayTypeInt16Array,
76     kJSTypedArrayTypeInt32Array,
77     kJSTypedArrayTypeUint8Array,
78     kJSTypedArrayTypeUint8ClampedArray,
79     kJSTypedArrayTypeUint16Array,
80     kJSTypedArrayTypeUint32Array,
81     kJSTypedArrayTypeFloat32Array,
82     kJSTypedArrayTypeFloat64Array,
83     kJSTypedArrayTypeArrayBuffer,
84     kJSTypedArrayTypeNone,
85 } JSTypedArrayType JSC_API_AVAILABLE(macosx(10.12), ios(10.0));
86
87 #ifdef __cplusplus
88 extern "C" {
89 #endif
90
91 /*!
92 @function
93 @abstract       Returns a JavaScript value's type.
94 @param ctx  The execution context to use.
95 @param value    The JSValue whose type you want to obtain.
96 @result         A value of type JSType that identifies value's type.
97 */
98 JS_EXPORT JSType JSValueGetType(JSContextRef ctx, JSValueRef value);
99
100 /*!
101 @function
102 @abstract       Tests whether a JavaScript value's type is the undefined type.
103 @param ctx  The execution context to use.
104 @param value    The JSValue to test.
105 @result         true if value's type is the undefined type, otherwise false.
106 */
107 JS_EXPORT bool JSValueIsUndefined(JSContextRef ctx, JSValueRef value);
108
109 /*!
110 @function
111 @abstract       Tests whether a JavaScript value's type is the null type.
112 @param ctx  The execution context to use.
113 @param value    The JSValue to test.
114 @result         true if value's type is the null type, otherwise false.
115 */
116 JS_EXPORT bool JSValueIsNull(JSContextRef ctx, JSValueRef value);
117
118 /*!
119 @function
120 @abstract       Tests whether a JavaScript value's type is the boolean type.
121 @param ctx  The execution context to use.
122 @param value    The JSValue to test.
123 @result         true if value's type is the boolean type, otherwise false.
124 */
125 JS_EXPORT bool JSValueIsBoolean(JSContextRef ctx, JSValueRef value);
126
127 /*!
128 @function
129 @abstract       Tests whether a JavaScript value's type is the number type.
130 @param ctx  The execution context to use.
131 @param value    The JSValue to test.
132 @result         true if value's type is the number type, otherwise false.
133 */
134 JS_EXPORT bool JSValueIsNumber(JSContextRef ctx, JSValueRef value);
135
136 /*!
137 @function
138 @abstract       Tests whether a JavaScript value's type is the string type.
139 @param ctx  The execution context to use.
140 @param value    The JSValue to test.
141 @result         true if value's type is the string type, otherwise false.
142 */
143 JS_EXPORT bool JSValueIsString(JSContextRef ctx, JSValueRef value);
144
145 /*!
146 @function
147 @abstract       Tests whether a JavaScript value's type is the object type.
148 @param ctx  The execution context to use.
149 @param value    The JSValue to test.
150 @result         true if value's type is the object type, otherwise false.
151 */
152 JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value);
153
154 /*!
155 @function
156 @abstract       Tests whether a JavaScript value's type is the symbol type.
157 @param ctx      The execution context to use.
158 @param value    The JSValue to test.
159 @result         true if value's type is the symbol type, otherwise false.
160 */
161 JS_EXPORT bool JSValueIsSymbol(JSContextRef ctx, JSValueRef value) JSC_API_AVAILABLE(macosx(JSC_MAC_TBA), ios(JSC_IOS_TBA));
162
163
164 /*!
165 @function
166 @abstract Tests whether a JavaScript value is an object with a given class in its class chain.
167 @param ctx The execution context to use.
168 @param value The JSValue to test.
169 @param jsClass The JSClass to test against.
170 @result true if value is an object and has jsClass in its class chain, otherwise false.
171 */
172 JS_EXPORT bool JSValueIsObjectOfClass(JSContextRef ctx, JSValueRef value, JSClassRef jsClass);
173
174 /*!
175 @function
176 @abstract       Tests whether a JavaScript value is an array.
177 @param ctx      The execution context to use.
178 @param value    The JSValue to test.
179 @result         true if value is an array, otherwise false.
180 */
181 JS_EXPORT bool JSValueIsArray(JSContextRef ctx, JSValueRef value) JSC_API_AVAILABLE(macosx(10.11), ios(9.0));
182
183 /*!
184 @function
185 @abstract       Tests whether a JavaScript value is a date.
186 @param ctx      The execution context to use.
187 @param value    The JSValue to test.
188 @result         true if value is a date, otherwise false.
189 */
190 JS_EXPORT bool JSValueIsDate(JSContextRef ctx, JSValueRef value) JSC_API_AVAILABLE(macosx(10.11), ios(9.0));
191
192 /*!
193 @function
194 @abstract           Returns a JavaScript value's Typed Array type.
195 @param ctx          The execution context to use.
196 @param value        The JSValue whose Typed Array type to return.
197 @param exception    A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
198 @result             A value of type JSTypedArrayType that identifies value's Typed Array type, or kJSTypedArrayTypeNone if the value is not a Typed Array object.
199  */
200 JS_EXPORT JSTypedArrayType JSValueGetTypedArrayType(JSContextRef ctx, JSValueRef value, JSValueRef* exception) JSC_API_AVAILABLE(macosx(10.12), ios(10.0));
201
202 /* Comparing values */
203
204 /*!
205 @function
206 @abstract Tests whether two JavaScript values are equal, as compared by the JS == operator.
207 @param ctx The execution context to use.
208 @param a The first value to test.
209 @param b The second value to test.
210 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
211 @result true if the two values are equal, false if they are not equal or an exception is thrown.
212 */
213 JS_EXPORT bool JSValueIsEqual(JSContextRef ctx, JSValueRef a, JSValueRef b, JSValueRef* exception);
214
215 /*!
216 @function
217 @abstract       Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
218 @param ctx  The execution context to use.
219 @param a        The first value to test.
220 @param b        The second value to test.
221 @result         true if the two values are strict equal, otherwise false.
222 */
223 JS_EXPORT bool JSValueIsStrictEqual(JSContextRef ctx, JSValueRef a, JSValueRef b);
224
225 /*!
226 @function
227 @abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
228 @param ctx The execution context to use.
229 @param value The JSValue to test.
230 @param constructor The constructor to test against.
231 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
232 @result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.
233 */
234 JS_EXPORT bool JSValueIsInstanceOfConstructor(JSContextRef ctx, JSValueRef value, JSObjectRef constructor, JSValueRef* exception);
235
236 /* Creating values */
237
238 /*!
239 @function
240 @abstract       Creates a JavaScript value of the undefined type.
241 @param ctx  The execution context to use.
242 @result         The unique undefined value.
243 */
244 JS_EXPORT JSValueRef JSValueMakeUndefined(JSContextRef ctx);
245
246 /*!
247 @function
248 @abstract       Creates a JavaScript value of the null type.
249 @param ctx  The execution context to use.
250 @result         The unique null value.
251 */
252 JS_EXPORT JSValueRef JSValueMakeNull(JSContextRef ctx);
253
254 /*!
255 @function
256 @abstract       Creates a JavaScript value of the boolean type.
257 @param ctx  The execution context to use.
258 @param boolean  The bool to assign to the newly created JSValue.
259 @result         A JSValue of the boolean type, representing the value of boolean.
260 */
261 JS_EXPORT JSValueRef JSValueMakeBoolean(JSContextRef ctx, bool boolean);
262
263 /*!
264 @function
265 @abstract       Creates a JavaScript value of the number type.
266 @param ctx  The execution context to use.
267 @param number   The double to assign to the newly created JSValue.
268 @result         A JSValue of the number type, representing the value of number.
269 */
270 JS_EXPORT JSValueRef JSValueMakeNumber(JSContextRef ctx, double number);
271
272 /*!
273 @function
274 @abstract            Creates a JavaScript value of the symbol type.
275 @param ctx           The execution context to use.
276 @param description   A description of the newly created symbol value.
277 @result              A unique JSValue of the symbol type, whose description matches the one provided.
278 */
279 JS_EXPORT JSValueRef JSValueMakeSymbol(JSContextRef ctx, JSStringRef description) JSC_API_AVAILABLE(macosx(JSC_MAC_TBA), ios(JSC_IOS_TBA));
280
281 /*!
282 @function
283 @abstract       Creates a JavaScript value of the string type.
284 @param ctx  The execution context to use.
285 @param string   The JSString to assign to the newly created JSValue. The
286  newly created JSValue retains string, and releases it upon garbage collection.
287 @result         A JSValue of the string type, representing the value of string.
288 */
289 JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string);
290
291 /* Converting to and from JSON formatted strings */
292
293 /*!
294  @function
295  @abstract       Creates a JavaScript value from a JSON formatted string.
296  @param ctx      The execution context to use.
297  @param string   The JSString containing the JSON string to be parsed.
298  @result         A JSValue containing the parsed value, or NULL if the input is invalid.
299  */
300 JS_EXPORT JSValueRef JSValueMakeFromJSONString(JSContextRef ctx, JSStringRef string) JSC_API_AVAILABLE(macosx(10.7), ios(7.0));
301
302 /*!
303  @function
304  @abstract       Creates a JavaScript string containing the JSON serialized representation of a JS value.
305  @param ctx      The execution context to use.
306  @param value    The value to serialize.
307  @param indent   The number of spaces to indent when nesting.  If 0, the resulting JSON will not contains newlines.  The size of the indent is clamped to 10 spaces.
308  @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
309  @result         A JSString with the result of serialization, or NULL if an exception is thrown.
310  */
311 JS_EXPORT JSStringRef JSValueCreateJSONString(JSContextRef ctx, JSValueRef value, unsigned indent, JSValueRef* exception) JSC_API_AVAILABLE(macosx(10.7), ios(7.0));
312
313 /* Converting to primitive values */
314
315 /*!
316 @function
317 @abstract       Converts a JavaScript value to boolean and returns the resulting boolean.
318 @param ctx  The execution context to use.
319 @param value    The JSValue to convert.
320 @result         The boolean result of conversion.
321 */
322 JS_EXPORT bool JSValueToBoolean(JSContextRef ctx, JSValueRef value);
323
324 /*!
325 @function
326 @abstract       Converts a JavaScript value to number and returns the resulting number.
327 @param ctx  The execution context to use.
328 @param value    The JSValue to convert.
329 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
330 @result         The numeric result of conversion, or NaN if an exception is thrown.
331 */
332 JS_EXPORT double JSValueToNumber(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
333
334 /*!
335 @function
336 @abstract       Converts a JavaScript value to string and copies the result into a JavaScript string.
337 @param ctx  The execution context to use.
338 @param value    The JSValue to convert.
339 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
340 @result         A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.
341 */
342 JS_EXPORT JSStringRef JSValueToStringCopy(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
343
344 /*!
345 @function
346 @abstract Converts a JavaScript value to object and returns the resulting object.
347 @param ctx  The execution context to use.
348 @param value    The JSValue to convert.
349 @param exception A pointer to a JSValueRef in which to store an exception, if any. Pass NULL if you do not care to store an exception.
350 @result         The JSObject result of conversion, or NULL if an exception is thrown.
351 */
352 JS_EXPORT JSObjectRef JSValueToObject(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
353
354 /* Garbage collection */
355 /*!
356 @function
357 @abstract Protects a JavaScript value from garbage collection.
358 @param ctx The execution context to use.
359 @param value The JSValue to protect.
360 @discussion Use this method when you want to store a JSValue in a global or on the heap, where the garbage collector will not be able to discover your reference to it.
361  
362 A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.
363 */
364 JS_EXPORT void JSValueProtect(JSContextRef ctx, JSValueRef value);
365
366 /*!
367 @function
368 @abstract       Unprotects a JavaScript value from garbage collection.
369 @param ctx      The execution context to use.
370 @param value    The JSValue to unprotect.
371 @discussion     A value may be protected multiple times and must be unprotected an 
372  equal number of times before becoming eligible for garbage collection.
373 */
374 JS_EXPORT void JSValueUnprotect(JSContextRef ctx, JSValueRef value);
375
376 #ifdef __cplusplus
377 }
378 #endif
379
380 #endif /* JSValueRef_h */