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 */
  46 typedef enum {
  47     kJSTypeUndefined,
  48     kJSTypeNull,
  49     kJSTypeBoolean,
  50     kJSTypeNumber,
  51     kJSTypeString,
  52     kJSTypeObject
  53 } JSType;
  54
  55 #ifdef __cplusplus
  56 extern "C" {
  57 #endif
  58
  59 /*!
  60 @function
  61 @abstract       Returns a JavaScript value's type.
  62 @param ctx  The execution context to use.
  63 @param value    The JSValue whose type you want to obtain.
  64 @result         A value of type JSType that identifies value's type.
  65 */
  66 JS_EXPORT JSType JSValueGetType(JSContextRef ctx, JSValueRef);
  67
  68 /*!
  69 @function
  70 @abstract       Tests whether a JavaScript value's type is the undefined type.
  71 @param ctx  The execution context to use.
  72 @param value    The JSValue to test.
  73 @result         true if value's type is the undefined type, otherwise false.
  74 */
  75 JS_EXPORT bool JSValueIsUndefined(JSContextRef ctx, JSValueRef value);
  76
  77 /*!
  78 @function
  79 @abstract       Tests whether a JavaScript value's type is the null type.
  80 @param ctx  The execution context to use.
  81 @param value    The JSValue to test.
  82 @result         true if value's type is the null type, otherwise false.
  83 */
  84 JS_EXPORT bool JSValueIsNull(JSContextRef ctx, JSValueRef value);
  85
  86 /*!
  87 @function
  88 @abstract       Tests whether a JavaScript value's type is the boolean type.
  89 @param ctx  The execution context to use.
  90 @param value    The JSValue to test.
  91 @result         true if value's type is the boolean type, otherwise false.
  92 */
  93 JS_EXPORT bool JSValueIsBoolean(JSContextRef ctx, JSValueRef value);
  94
  95 /*!
  96 @function
  97 @abstract       Tests whether a JavaScript value's type is the number type.
  98 @param ctx  The execution context to use.
  99 @param value    The JSValue to test.
 100 @result         true if value's type is the number type, otherwise false.
 101 */
 102 JS_EXPORT bool JSValueIsNumber(JSContextRef ctx, JSValueRef value);
 103
 104 /*!
 105 @function
 106 @abstract       Tests whether a JavaScript value's type is the string type.
 107 @param ctx  The execution context to use.
 108 @param value    The JSValue to test.
 109 @result         true if value's type is the string type, otherwise false.
 110 */
 111 JS_EXPORT bool JSValueIsString(JSContextRef ctx, JSValueRef value);
 112
 113 /*!
 114 @function
 115 @abstract       Tests whether a JavaScript value's type is the object type.
 116 @param ctx  The execution context to use.
 117 @param value    The JSValue to test.
 118 @result         true if value's type is the object type, otherwise false.
 119 */
 120 JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value);
 121
 122 /*!
 123 @function
 124 @abstract Tests whether a JavaScript value is an object with a given class in its class chain.
 125 @param ctx The execution context to use.
 126 @param value The JSValue to test.
 127 @param jsClass The JSClass to test against.
 128 @result true if value is an object and has jsClass in its class chain, otherwise false.
 129 */
 130 JS_EXPORT bool JSValueIsObjectOfClass(JSContextRef ctx, JSValueRef value, JSClassRef jsClass);
 131
 132 /*!
 133 @function
 134 @abstract       Tests whether a JavaScript value is an array.
 135 @param ctx      The execution context to use.
 136 @param value    The JSValue to test.
 137 @result         true if value is an array, otherwise false.
 138 */
 139 JS_EXPORT bool JSValueIsArray(JSContextRef ctx, JSValueRef value) CF_AVAILABLE(10_11, 9_0);
 140
 141 /*!
 142 @function
 143 @abstract       Tests whether a JavaScript value is a date.
 144 @param ctx      The execution context to use.
 145 @param value    The JSValue to test.
 146 @result         true if value is a date, otherwise false.
 147 */
 148 JS_EXPORT bool JSValueIsDate(JSContextRef ctx, JSValueRef value) CF_AVAILABLE(10_11, 9_0);
 149
 150 /* Comparing values */
 151
 152 /*!
 153 @function
 154 @abstract Tests whether two JavaScript values are equal, as compared by the JS == operator.
 155 @param ctx The execution context to use.
 156 @param a The first value to test.
 157 @param b The second value to test.
 158 @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.
 159 @result true if the two values are equal, false if they are not equal or an exception is thrown.
 160 */
 161 JS_EXPORT bool JSValueIsEqual(JSContextRef ctx, JSValueRef a, JSValueRef b, JSValueRef* exception);
 162
 163 /*!
 164 @function
 165 @abstract       Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
 166 @param ctx  The execution context to use.
 167 @param a        The first value to test.
 168 @param b        The second value to test.
 169 @result         true if the two values are strict equal, otherwise false.
 170 */
 171 JS_EXPORT bool JSValueIsStrictEqual(JSContextRef ctx, JSValueRef a, JSValueRef b);
 172
 173 /*!
 174 @function
 175 @abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
 176 @param ctx The execution context to use.
 177 @param value The JSValue to test.
 178 @param constructor The constructor to test against.
 179 @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.
 180 @result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.
 181 */
 182 JS_EXPORT bool JSValueIsInstanceOfConstructor(JSContextRef ctx, JSValueRef value, JSObjectRef constructor, JSValueRef* exception);
 183
 184 /* Creating values */
 185
 186 /*!
 187 @function
 188 @abstract       Creates a JavaScript value of the undefined type.
 189 @param ctx  The execution context to use.
 190 @result         The unique undefined value.
 191 */
 192 JS_EXPORT JSValueRef JSValueMakeUndefined(JSContextRef ctx);
 193
 194 /*!
 195 @function
 196 @abstract       Creates a JavaScript value of the null type.
 197 @param ctx  The execution context to use.
 198 @result         The unique null value.
 199 */
 200 JS_EXPORT JSValueRef JSValueMakeNull(JSContextRef ctx);
 201
 202 /*!
 203 @function
 204 @abstract       Creates a JavaScript value of the boolean type.
 205 @param ctx  The execution context to use.
 206 @param boolean  The bool to assign to the newly created JSValue.
 207 @result         A JSValue of the boolean type, representing the value of boolean.
 208 */
 209 JS_EXPORT JSValueRef JSValueMakeBoolean(JSContextRef ctx, bool boolean);
 210
 211 /*!
 212 @function
 213 @abstract       Creates a JavaScript value of the number type.
 214 @param ctx  The execution context to use.
 215 @param number   The double to assign to the newly created JSValue.
 216 @result         A JSValue of the number type, representing the value of number.
 217 */
 218 JS_EXPORT JSValueRef JSValueMakeNumber(JSContextRef ctx, double number);
 219
 220 /*!
 221 @function
 222 @abstract       Creates a JavaScript value of the string type.
 223 @param ctx  The execution context to use.
 224 @param string   The JSString to assign to the newly created JSValue. The
 225  newly created JSValue retains string, and releases it upon garbage collection.
 226 @result         A JSValue of the string type, representing the value of string.
 227 */
 228 JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string);
 229
 230 /* Converting to and from JSON formatted strings */
 231
 232 /*!
 233  @function
 234  @abstract       Creates a JavaScript value from a JSON formatted string.
 235  @param ctx      The execution context to use.
 236  @param string   The JSString containing the JSON string to be parsed.
 237  @result         A JSValue containing the parsed value, or NULL if the input is invalid.
 238  */
 239 JS_EXPORT JSValueRef JSValueMakeFromJSONString(JSContextRef ctx, JSStringRef string) CF_AVAILABLE(10_7, 7_0);
 240
 241 /*!
 242  @function
 243  @abstract       Creates a JavaScript string containing the JSON serialized representation of a JS value.
 244  @param ctx      The execution context to use.
 245  @param value    The value to serialize.
 246  @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.
 247  @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.
 248  @result         A JSString with the result of serialization, or NULL if an exception is thrown.
 249  */
 250 JS_EXPORT JSStringRef JSValueCreateJSONString(JSContextRef ctx, JSValueRef value, unsigned indent, JSValueRef* exception) CF_AVAILABLE(10_7, 7_0);
 251
 252 /* Converting to primitive values */
 253
 254 /*!
 255 @function
 256 @abstract       Converts a JavaScript value to boolean and returns the resulting boolean.
 257 @param ctx  The execution context to use.
 258 @param value    The JSValue to convert.
 259 @result         The boolean result of conversion.
 260 */
 261 JS_EXPORT bool JSValueToBoolean(JSContextRef ctx, JSValueRef value);
 262
 263 /*!
 264 @function
 265 @abstract       Converts a JavaScript value to number and returns the resulting number.
 266 @param ctx  The execution context to use.
 267 @param value    The JSValue to convert.
 268 @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.
 269 @result         The numeric result of conversion, or NaN if an exception is thrown.
 270 */
 271 JS_EXPORT double JSValueToNumber(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
 272
 273 /*!
 274 @function
 275 @abstract       Converts a JavaScript value to string and copies the result into a JavaScript string.
 276 @param ctx  The execution context to use.
 277 @param value    The JSValue to convert.
 278 @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.
 279 @result         A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.
 280 */
 281 JS_EXPORT JSStringRef JSValueToStringCopy(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
 282
 283 /*!
 284 @function
 285 @abstract Converts a JavaScript value to object and returns the resulting object.
 286 @param ctx  The execution context to use.
 287 @param value    The JSValue to convert.
 288 @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.
 289 @result         The JSObject result of conversion, or NULL if an exception is thrown.
 290 */
 291 JS_EXPORT JSObjectRef JSValueToObject(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
 292
 293 /* Garbage collection */
 294 /*!
 295 @function
 296 @abstract Protects a JavaScript value from garbage collection.
 297 @param ctx The execution context to use.
 298 @param value The JSValue to protect.
 299 @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.
 300
 301 A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.
 302 */
 303 JS_EXPORT void JSValueProtect(JSContextRef ctx, JSValueRef value);
 304
 305 /*!
 306 @function
 307 @abstract       Unprotects a JavaScript value from garbage collection.
 308 @param ctx      The execution context to use.
 309 @param value    The JSValue to unprotect.
 310 @discussion     A value may be protected multiple times and must be unprotected an
 311  equal number of times before becoming eligible for garbage collection.
 312 */
 313 JS_EXPORT void JSValueUnprotect(JSContextRef ctx, JSValueRef value);
 314
 315 #ifdef __cplusplus
 316 }
 317 #endif
 318
 319 #endif /* JSValueRef_h */