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