API/JSValueRef.h

   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 */