1  /*
  2   * Copyright (C) 2006-2019 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(macos(10.15), ios(13.0))
 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(macos(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 symbol 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 symbol type, otherwise false.
151  */
152  JS_EXPORT bool JSValueIsSymbol(JSContextRef ctx, JSValueRef value) JSC_API_AVAILABLE(macos(10.15), ios(13.0));
153  
154  /*!
155  @function
156  @abstract       Tests whether a JavaScript value's type is the object 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 object type, otherwise false.
160  */
161  JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value);
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(macos(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(macos(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(macos(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 string type.
275  @param ctx  The execution context to use.
276  @param string   The JSString to assign to the newly created JSValue. The
277   newly created JSValue retains string, and releases it upon garbage collection.
278  @result         A JSValue of the string type, representing the value of string.
279  */
280  JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string);
281  
282  /*!
283   @function
284   @abstract            Creates a JavaScript value of the symbol type.
285   @param ctx           The execution context to use.
286   @param description   A description of the newly created symbol value.
287   @result              A unique JSValue of the symbol type, whose description matches the one provided.
288   */
289  JS_EXPORT JSValueRef JSValueMakeSymbol(JSContextRef ctx, JSStringRef description) JSC_API_AVAILABLE(macos(10.15), ios(13.0));
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(macos(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(macos(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 */