API/JSValueRef.h

   1 // -*- mode: c++; c-basic-offset: 4 -*-
   2 /*
   3  * Copyright (C) 2006 Apple Computer, Inc.  All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY APPLE COMPUTER, INC. ``AS IS'' AND ANY
  15  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  17  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE COMPUTER, INC. OR
  18  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  19  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  20  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  21  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  22  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  23  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  24  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  25  */
  26
  27 #ifndef JSValueRef_h
  28 #define JSValueRef_h
  29
  30 #include <JavaScriptCore/JSBase.h>
  31
  32 #include <stdbool.h>
  33
  34 /*!
  35 @enum JSType
  36 @abstract     A constant identifying the type of a JSValue.
  37 @constant     kJSTypeUndefined  The unique undefined value.
  38 @constant     kJSTypeNull       The unique null value.
  39 @constant     kJSTypeBoolean    A primitive boolean value, one of true or false.
  40 @constant     kJSTypeNumber     A primitive number value.
  41 @constant     kJSTypeString     A primitive string value.
  42 @constant     kJSTypeObject     An object value (meaning that this JSValueRef is a JSObjectRef).
  43 */
  44 typedef enum {
  45     kJSTypeUndefined,
  46     kJSTypeNull,
  47     kJSTypeBoolean,
  48     kJSTypeNumber,
  49     kJSTypeString,
  50     kJSTypeObject
  51 } JSType;
  52
  53 #ifdef __cplusplus
  54 extern "C" {
  55 #endif
  56
  57 /*!
  58 @function
  59 @abstract       Returns a JavaScript value's type.
  60 @param ctx  The execution context to use.
  61 @param value    The JSValue whose type you want to obtain.
  62 @result         A value of type JSType that identifies value's type.
  63 */
  64 JS_EXPORT JSType JSValueGetType(JSContextRef ctx, JSValueRef value);
  65
  66 /*!
  67 @function
  68 @abstract       Tests whether a JavaScript value's type is the undefined type.
  69 @param ctx  The execution context to use.
  70 @param value    The JSValue to test.
  71 @result         true if value's type is the undefined type, otherwise false.
  72 */
  73 JS_EXPORT bool JSValueIsUndefined(JSContextRef ctx, JSValueRef value);
  74
  75 /*!
  76 @function
  77 @abstract       Tests whether a JavaScript value's type is the null type.
  78 @param ctx  The execution context to use.
  79 @param value    The JSValue to test.
  80 @result         true if value's type is the null type, otherwise false.
  81 */
  82 JS_EXPORT bool JSValueIsNull(JSContextRef ctx, JSValueRef value);
  83
  84 /*!
  85 @function
  86 @abstract       Tests whether a JavaScript value's type is the boolean type.
  87 @param ctx  The execution context to use.
  88 @param value    The JSValue to test.
  89 @result         true if value's type is the boolean type, otherwise false.
  90 */
  91 JS_EXPORT bool JSValueIsBoolean(JSContextRef ctx, JSValueRef value);
  92
  93 /*!
  94 @function
  95 @abstract       Tests whether a JavaScript value's type is the number type.
  96 @param ctx  The execution context to use.
  97 @param value    The JSValue to test.
  98 @result         true if value's type is the number type, otherwise false.
  99 */
 100 JS_EXPORT bool JSValueIsNumber(JSContextRef ctx, JSValueRef value);
 101
 102 /*!
 103 @function
 104 @abstract       Tests whether a JavaScript value's type is the string type.
 105 @param ctx  The execution context to use.
 106 @param value    The JSValue to test.
 107 @result         true if value's type is the string type, otherwise false.
 108 */
 109 JS_EXPORT bool JSValueIsString(JSContextRef ctx, JSValueRef value);
 110
 111 /*!
 112 @function
 113 @abstract       Tests whether a JavaScript value's type is the object type.
 114 @param ctx  The execution context to use.
 115 @param value    The JSValue to test.
 116 @result         true if value's type is the object type, otherwise false.
 117 */
 118 JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value);
 119
 120 /*!
 121 @function
 122 @abstract Tests whether a JavaScript value is an object with a given class in its class chain.
 123 @param ctx The execution context to use.
 124 @param value The JSValue to test.
 125 @param jsClass The JSClass to test against.
 126 @result true if value is an object and has jsClass in its class chain, otherwise false.
 127 */
 128 JS_EXPORT bool JSValueIsObjectOfClass(JSContextRef ctx, JSValueRef value, JSClassRef jsClass);
 129
 130 // Comparing values
 131
 132 /*!
 133 @function
 134 @abstract Tests whether two JavaScript values are equal, as compared by the JS == operator.
 135 @param ctx The execution context to use.
 136 @param a The first value to test.
 137 @param b The second value to test.
 138 @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.
 139 @result true if the two values are equal, false if they are not equal or an exception is thrown.
 140 */
 141 JS_EXPORT bool JSValueIsEqual(JSContextRef ctx, JSValueRef a, JSValueRef b, JSValueRef* exception);
 142
 143 /*!
 144 @function
 145 @abstract       Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
 146 @param ctx  The execution context to use.
 147 @param a        The first value to test.
 148 @param b        The second value to test.
 149 @result         true if the two values are strict equal, otherwise false.
 150 */
 151 JS_EXPORT bool JSValueIsStrictEqual(JSContextRef ctx, JSValueRef a, JSValueRef b);
 152
 153 /*!
 154 @function
 155 @abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
 156 @param ctx The execution context to use.
 157 @param value The JSValue to test.
 158 @param constructor The constructor to test against.
 159 @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.
 160 @result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.
 161 */
 162 JS_EXPORT bool JSValueIsInstanceOfConstructor(JSContextRef ctx, JSValueRef value, JSObjectRef constructor, JSValueRef* exception);
 163
 164 // Creating values
 165
 166 /*!
 167 @function
 168 @abstract       Creates a JavaScript value of the undefined type.
 169 @param ctx  The execution context to use.
 170 @result         The unique undefined value.
 171 */
 172 JS_EXPORT JSValueRef JSValueMakeUndefined(JSContextRef ctx);
 173
 174 /*!
 175 @function
 176 @abstract       Creates a JavaScript value of the null type.
 177 @param ctx  The execution context to use.
 178 @result         The unique null value.
 179 */
 180 JS_EXPORT JSValueRef JSValueMakeNull(JSContextRef ctx);
 181
 182 /*!
 183 @function
 184 @abstract       Creates a JavaScript value of the boolean type.
 185 @param ctx  The execution context to use.
 186 @param boolean  The bool to assign to the newly created JSValue.
 187 @result         A JSValue of the boolean type, representing the value of boolean.
 188 */
 189 JS_EXPORT JSValueRef JSValueMakeBoolean(JSContextRef ctx, bool boolean);
 190
 191 /*!
 192 @function
 193 @abstract       Creates a JavaScript value of the number type.
 194 @param ctx  The execution context to use.
 195 @param number   The double to assign to the newly created JSValue.
 196 @result         A JSValue of the number type, representing the value of number.
 197 */
 198 JS_EXPORT JSValueRef JSValueMakeNumber(JSContextRef ctx, double number);
 199
 200 /*!
 201 @function
 202 @abstract       Creates a JavaScript value of the string type.
 203 @param ctx  The execution context to use.
 204 @param string   The JSString to assign to the newly created JSValue. The
 205  newly created JSValue retains string, and releases it upon garbage collection.
 206 @result         A JSValue of the string type, representing the value of string.
 207 */
 208 JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string);
 209
 210 // Converting to primitive values
 211
 212 /*!
 213 @function
 214 @abstract       Converts a JavaScript value to boolean and returns the resulting boolean.
 215 @param ctx  The execution context to use.
 216 @param value    The JSValue to convert.
 217 @result         The boolean result of conversion.
 218 */
 219 JS_EXPORT bool JSValueToBoolean(JSContextRef ctx, JSValueRef value);
 220
 221 /*!
 222 @function
 223 @abstract       Converts a JavaScript value to number and returns the resulting number.
 224 @param ctx  The execution context to use.
 225 @param value    The JSValue to convert.
 226 @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.
 227 @result         The numeric result of conversion, or NaN if an exception is thrown.
 228 */
 229 JS_EXPORT double JSValueToNumber(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
 230
 231 /*!
 232 @function
 233 @abstract       Converts a JavaScript value to string and copies the result into a JavaScript string.
 234 @param ctx  The execution context to use.
 235 @param value    The JSValue to convert.
 236 @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.
 237 @result         A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.
 238 */
 239 JS_EXPORT JSStringRef JSValueToStringCopy(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
 240
 241 /*!
 242 @function
 243 @abstract Converts a JavaScript value to object and returns the resulting object.
 244 @param ctx  The execution context to use.
 245 @param value    The JSValue to convert.
 246 @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.
 247 @result         The JSObject result of conversion, or NULL if an exception is thrown.
 248 */
 249 JS_EXPORT JSObjectRef JSValueToObject(JSContextRef ctx, JSValueRef value, JSValueRef* exception);
 250
 251 // Garbage collection
 252 /*!
 253 @function
 254 @abstract Protects a JavaScript value from garbage collection.
 255 @param ctx The execution context to use.
 256 @param value The JSValue to protect.
 257 @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.
 258
 259 A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.
 260 */
 261 JS_EXPORT void JSValueProtect(JSContextRef ctx, JSValueRef value);
 262
 263 /*!
 264 @function
 265 @abstract       Unprotects a JavaScript value from garbage collection.
 266 @param ctx      The execution context to use.
 267 @param value    The JSValue to unprotect.
 268 @discussion     A value may be protected multiple times and must be unprotected an
 269  equal number of times before becoming eligible for garbage collection.
 270 */
 271 JS_EXPORT void JSValueUnprotect(JSContextRef ctx, JSValueRef value);
 272
 273 #ifdef __cplusplus
 274 }
 275 #endif
 276
 277 #endif // JSValueRef_h