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