Reviewed by Geoff.
[WebKit-https.git] / JavaScriptCore / 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 "JSBase.h"
31
32 /*!
33   @enum JSTypeCode
34   A constant identifying the type of a particular JSValueRef.
35   @constant kJSTypeUndefined the unique undefined value
36   @constant kJSTypeNull the unique null value
37   @constant kJSBoolean a primitive boolean value, one of true or false
38   @constant kJSTypeNumber a primitive number value
39   @constant kJSTypeString a primitive string value
40   @constant kJSTypeObject an object (meaning this JSValueRef is a JSObjectRef
41 */
42 typedef enum {
43     kJSTypeUndefined,
44     kJSTypeNull,
45     kJSTypeBoolean,
46     kJSTypeNumber,
47     kJSTypeString,
48     kJSTypeObject
49 } JSTypeCode;
50
51 #ifdef __cplusplus
52 extern "C" {
53 #endif
54
55 /*!
56   @function JSValueGetType
57   Get the type code for a particular JavaScript value
58   @param value the JS value for which the type should be determined
59   @result      a type code identifying the type
60 */
61 JSTypeCode JSValueGetType(JSValueRef value);
62
63 /*!
64   @function JSValueIsUndefined
65   Determine if value is of type undefined
66   @param value the JS value to check for undefined type
67   @result      true if the value is undefined, false otherwise
68 */
69 bool JSValueIsUndefined(JSValueRef value);
70
71 /*!
72   @function JSValueIsNull
73   Determine if value is of type null
74   @param value the JS value to check for null type
75   @result      true if the value is null, false otherwise
76 */
77 bool JSValueIsNull(JSValueRef value);
78
79 /*!
80   @function JSValueIsBoolean
81   Determine if value is of type boolean
82   @param value the JS value to check for boolean type
83   @result      true if the value is a boolean, false otherwise
84 */
85 bool JSValueIsBoolean(JSValueRef value);
86
87 /*!
88   @function JSValueIsNumber
89   Determine if value is of type number
90   @param value the JS value to check for number type
91   @result      true if the value is a number, false otherwise
92 */
93 bool JSValueIsNumber(JSValueRef value);
94
95 /*!
96   @function JSValueIsString
97   Determine if value is of type string
98   @param value the JS value to check for string type
99   @result      true if the value is a string, false otherwise
100 */
101 bool JSValueIsString(JSValueRef value);
102
103 /*!
104   @function JSValueIsObject
105   Determine if value is of type object
106   @param value the JS value to check for object type
107   @result      true if the value is an object, false otherwise
108 */
109 bool JSValueIsObject(JSValueRef value);
110
111 // Comparing values
112
113 /*!
114   @function JSValueIsEqual
115   Check if two values are equal by JavaScript rules, as if compared by the JS == operator
116   @param context the execution context to use 
117   @param a       the first value to compare
118   @param b       the second value to compare
119   @result        true if the two values are equal, false otherwise
120 */
121 bool JSValueIsEqual(JSContextRef context, JSValueRef a, JSValueRef b);
122
123 /*!
124   @function JSValueIsStrictEqual
125   Check if two values are strict equal by JavaScript rules, as if compared by the JS === operator
126   @param context the execution context to use 
127   @param a       the first value to compare
128   @param b       the second value to compare
129   @result        true if the two values are strict equal, false otherwise
130 */
131 bool JSValueIsStrictEqual(JSContextRef context, JSValueRef a, JSValueRef b);
132
133 /*!
134   @function JSValueIsInstanceOf
135   Check if a value is an instance of a particular object; generally this means the object
136   was used as the constructor for that instance
137   @param context the execution context to use 
138   @param value   the possible instance
139   @param object  the possible constructor
140   @result        true if value is an instance of object
141 */
142 bool JSValueIsInstanceOf(JSValueRef value, JSObjectRef object);
143
144 // Creating values
145
146 /*!
147   @function JSUndefinedMake
148   Make a value of the undefined type.
149   @result The unique undefined value.
150 */
151 JSValueRef JSUndefinedMake(void);
152
153 /*!
154   @function JSNullMake
155   Make a value of the null type.
156   @result the unique null value
157 */
158 JSValueRef JSNullMake(void);
159
160 /*!
161   @function JSBooleanMake
162   Make a value of the boolean type.
163   @param value whether the returned value should be true or false
164   @result      a JS true or false boolean value, as appropriate
165 */
166
167 JSValueRef JSBooleanMake(bool value);
168
169 /*!
170   @function JSNumberMake
171   Make a value of the number type.
172   @param  value the numberic value of the number to make
173   @result a JS number corresponding to value
174 */
175 JSValueRef JSNumberMake(double value);
176
177 /*!
178   @function JSStringMake
179   Make a value of the string type.
180   @param  buffer the internal string contents for the string value
181   @result a JS string value that has the value of the buffer
182 */
183 JSValueRef JSStringMake(JSCharBufferRef buffer);
184
185 // Converting to primitive values
186
187 /*!
188   @function JSValueToBoolean
189   Convert a JavaScript value to boolean and get the boolean value
190   @param context the execution context to use 
191   @param value   the value to convert to boolean
192   @result        the boolean result of conversion
193 */
194 bool JSValueToBoolean(JSContextRef context, JSValueRef value);
195
196 /*!
197   @function JSValueToNumber
198   Convert a JavaScript value to number and get the numeric value
199   @param context the execution context to use 
200   @param value   the value to convert to number
201   @result        the boolean result of conversion, or 0 on failure
202 */
203 double JSValueToNumber(JSContextRef context, JSValueRef value);
204
205 /*!
206   @function JSValueCopyStringValue
207   Convert a JavaScript value to string and get the value as a string
208   @param context the execution context to use 
209   @param value   the value to convert to string
210   @result        the string result of conversion, or empty string on failure
211 */
212 JSCharBufferRef JSValueCopyStringValue(JSContextRef context, JSValueRef value);
213
214 /*!
215   @function JSValueToObject
216   Convert a JavaScript value to object and return the resulting object
217   @param context the execution context to use 
218   @param value   the value to convert to string
219   @result        the string result of conversion, or error object on failure
220 */
221 JSObjectRef JSValueToObject(JSContextRef context, JSValueRef value);
222
223 #ifdef __cplusplus
224 }
225 #endif
226
227 #endif // JSValueRef_h