[apple/javascriptcore.git] / API / JSValueRef.h

/*
 * Copyright (C) 2006 Apple Inc.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#ifndef JSValueRef_h
#define JSValueRef_h

#include <JavaScriptCore/JSBase.h>
#include <JavaScriptCore/WebKitAvailability.h>

#ifndef __cplusplus
#include <stdbool.h>
#endif

/*!
@enum JSType
@abstract     A constant identifying the type of a JSValue.
@constant     kJSTypeUndefined  The unique undefined value.
@constant     kJSTypeNull       The unique null value.
@constant     kJSTypeBoolean    A primitive boolean value, one of true or false.
@constant     kJSTypeNumber     A primitive number value.
@constant     kJSTypeString     A primitive string value.
@constant     kJSTypeObject     An object value (meaning that this JSValueRef is a JSObjectRef).
*/
typedef enum {
    kJSTypeUndefined,
    kJSTypeNull,
    kJSTypeBoolean,
    kJSTypeNumber,
    kJSTypeString,
    kJSTypeObject
} JSType;

#ifdef __cplusplus
extern "C" {
#endif

/*!
@function
@abstract       Returns a JavaScript value's type.
@param ctx  The execution context to use.
@param value    The JSValue whose type you want to obtain.
@result         A value of type JSType that identifies value's type.
*/
JS_EXPORT JSType JSValueGetType(JSContextRef ctx, JSValueRef);

/*!
@function
@abstract       Tests whether a JavaScript value's type is the undefined type.
@param ctx  The execution context to use.
@param value    The JSValue to test.
@result         true if value's type is the undefined type, otherwise false.
*/
JS_EXPORT bool JSValueIsUndefined(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Tests whether a JavaScript value's type is the null type.
@param ctx  The execution context to use.
@param value    The JSValue to test.
@result         true if value's type is the null type, otherwise false.
*/
JS_EXPORT bool JSValueIsNull(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Tests whether a JavaScript value's type is the boolean type.
@param ctx  The execution context to use.
@param value    The JSValue to test.
@result         true if value's type is the boolean type, otherwise false.
*/
JS_EXPORT bool JSValueIsBoolean(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Tests whether a JavaScript value's type is the number type.
@param ctx  The execution context to use.
@param value    The JSValue to test.
@result         true if value's type is the number type, otherwise false.
*/
JS_EXPORT bool JSValueIsNumber(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Tests whether a JavaScript value's type is the string type.
@param ctx  The execution context to use.
@param value    The JSValue to test.
@result         true if value's type is the string type, otherwise false.
*/
JS_EXPORT bool JSValueIsString(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Tests whether a JavaScript value's type is the object type.
@param ctx  The execution context to use.
@param value    The JSValue to test.
@result         true if value's type is the object type, otherwise false.
*/
JS_EXPORT bool JSValueIsObject(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract Tests whether a JavaScript value is an object with a given class in its class chain.
@param ctx The execution context to use.
@param value The JSValue to test.
@param jsClass The JSClass to test against.
@result true if value is an object and has jsClass in its class chain, otherwise false.
*/
JS_EXPORT bool JSValueIsObjectOfClass(JSContextRef ctx, JSValueRef value, JSClassRef jsClass);

/* Comparing values */

/*!
@function
@abstract Tests whether two JavaScript values are equal, as compared by the JS == operator.
@param ctx The execution context to use.
@param a The first value to test.
@param b The second value to test.
@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.
@result true if the two values are equal, false if they are not equal or an exception is thrown.
*/
JS_EXPORT bool JSValueIsEqual(JSContextRef ctx, JSValueRef a, JSValueRef b, JSValueRef* exception);

/*!
@function
@abstract       Tests whether two JavaScript values are strict equal, as compared by the JS === operator.
@param ctx  The execution context to use.
@param a        The first value to test.
@param b        The second value to test.
@result         true if the two values are strict equal, otherwise false.
*/
JS_EXPORT bool JSValueIsStrictEqual(JSContextRef ctx, JSValueRef a, JSValueRef b);

/*!
@function
@abstract Tests whether a JavaScript value is an object constructed by a given constructor, as compared by the JS instanceof operator.
@param ctx The execution context to use.
@param value The JSValue to test.
@param constructor The constructor to test against.
@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.
@result true if value is an object constructed by constructor, as compared by the JS instanceof operator, otherwise false.
*/
JS_EXPORT bool JSValueIsInstanceOfConstructor(JSContextRef ctx, JSValueRef value, JSObjectRef constructor, JSValueRef* exception);

/* Creating values */

/*!
@function
@abstract       Creates a JavaScript value of the undefined type.
@param ctx  The execution context to use.
@result         The unique undefined value.
*/
JS_EXPORT JSValueRef JSValueMakeUndefined(JSContextRef ctx);

/*!
@function
@abstract       Creates a JavaScript value of the null type.
@param ctx  The execution context to use.
@result         The unique null value.
*/
JS_EXPORT JSValueRef JSValueMakeNull(JSContextRef ctx);

/*!
@function
@abstract       Creates a JavaScript value of the boolean type.
@param ctx  The execution context to use.
@param boolean  The bool to assign to the newly created JSValue.
@result         A JSValue of the boolean type, representing the value of boolean.
*/
JS_EXPORT JSValueRef JSValueMakeBoolean(JSContextRef ctx, bool boolean);

/*!
@function
@abstract       Creates a JavaScript value of the number type.
@param ctx  The execution context to use.
@param number   The double to assign to the newly created JSValue.
@result         A JSValue of the number type, representing the value of number.
*/
JS_EXPORT JSValueRef JSValueMakeNumber(JSContextRef ctx, double number);

/*!
@function
@abstract       Creates a JavaScript value of the string type.
@param ctx  The execution context to use.
@param string   The JSString to assign to the newly created JSValue. The
 newly created JSValue retains string, and releases it upon garbage collection.
@result         A JSValue of the string type, representing the value of string.
*/
JS_EXPORT JSValueRef JSValueMakeString(JSContextRef ctx, JSStringRef string);

/* Converting to and from JSON formatted strings */

/*!
 @function
 @abstract       Creates a JavaScript value from a JSON formatted string.
 @param ctx      The execution context to use.
 @param string   The JSString containing the JSON string to be parsed.
 @result         A JSValue containing the parsed value, or NULL if the input is invalid.
 */
JS_EXPORT JSValueRef JSValueMakeFromJSONString(JSContextRef ctx, JSStringRef string) CF_AVAILABLE(10_7, 7_0);

/*!
 @function
 @abstract       Creates a JavaScript string containing the JSON serialized representation of a JS value.
 @param ctx      The execution context to use.
 @param value    The value to serialize.
 @param indent   The number of spaces to indent when nesting.  If 0, the resulting JSON will not contains newlines.  The size of the indent is clamped to 10 spaces.
 @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.
 @result         A JSString with the result of serialization, or NULL if an exception is thrown.
 */
JS_EXPORT JSStringRef JSValueCreateJSONString(JSContextRef ctx, JSValueRef value, unsigned indent, JSValueRef* exception) CF_AVAILABLE(10_7, 7_0);

/* Converting to primitive values */

/*!
@function
@abstract       Converts a JavaScript value to boolean and returns the resulting boolean.
@param ctx  The execution context to use.
@param value    The JSValue to convert.
@result         The boolean result of conversion.
*/
JS_EXPORT bool JSValueToBoolean(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Converts a JavaScript value to number and returns the resulting number.
@param ctx  The execution context to use.
@param value    The JSValue to convert.
@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.
@result         The numeric result of conversion, or NaN if an exception is thrown.
*/
JS_EXPORT double JSValueToNumber(JSContextRef ctx, JSValueRef value, JSValueRef* exception);

/*!
@function
@abstract       Converts a JavaScript value to string and copies the result into a JavaScript string.
@param ctx  The execution context to use.
@param value    The JSValue to convert.
@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.
@result         A JSString with the result of conversion, or NULL if an exception is thrown. Ownership follows the Create Rule.
*/
JS_EXPORT JSStringRef JSValueToStringCopy(JSContextRef ctx, JSValueRef value, JSValueRef* exception);

/*!
@function
@abstract Converts a JavaScript value to object and returns the resulting object.
@param ctx  The execution context to use.
@param value    The JSValue to convert.
@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.
@result         The JSObject result of conversion, or NULL if an exception is thrown.
*/
JS_EXPORT JSObjectRef JSValueToObject(JSContextRef ctx, JSValueRef value, JSValueRef* exception);

/* Garbage collection */
/*!
@function
@abstract Protects a JavaScript value from garbage collection.
@param ctx The execution context to use.
@param value The JSValue to protect.
@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.
 
A value may be protected multiple times and must be unprotected an equal number of times before becoming eligible for garbage collection.
*/
JS_EXPORT void JSValueProtect(JSContextRef ctx, JSValueRef value);

/*!
@function
@abstract       Unprotects a JavaScript value from garbage collection.
@param ctx      The execution context to use.
@param value    The JSValue to unprotect.
@discussion     A value may be protected multiple times and must be unprotected an 
 equal number of times before becoming eligible for garbage collection.
*/
JS_EXPORT void JSValueUnprotect(JSContextRef ctx, JSValueRef value);

#ifdef __cplusplus
}
#endif

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