JS DefinePropertyWithTinyId

From MDC

Create a new object property with a tiny id.

[edit] Syntax

JSBool JS_DefinePropertyWithTinyId(JSContext *cx,
    JSObject *obj, const char *name, int8 tinyid, jsval value,
    JSPropertyOp getter, JSPropertyOp setter, uintN attrs);

JSBool JS_DefineUCPropertyWithTinyId(JSContext *cx,
    JSObject *obj, const jschar *name, size_t namelen,
    int8 tinyid, jsval value, JSPropertyOp getter,
    JSPropertyOp setter, uintN attrs);

Name	Type	Description
cx	JSContext *	The context in which to define the property. Requires request. (In a JS_THREADSAFE build, the caller must be in a request on this JSContext.)
obj	JSObject *	Object for which to create the new property.
name	const char * or const jschar *	Name for the property to create.
namelen	size_t	(only in JS_DefineUCPropertyWithTinyId) The length of name in characters; or (size_t) -1 to indicate that name is null-terminated.
tinyid	int8	8-bit ID to aid in sharing getter and setter callbacks among properties.
value	jsval	Initial stored value for the new property.
getter	JSPropertyOp	getProperty method for retrieving the current property value.
setter	JSPropertyOp	setProperty method for specifying a new property value.
attrs	uintN	Property attributes.

[edit] Description

JS_DefinePropertyWithTinyId defines an object property with a tiny id. JS_DefineUCPropertyWithTinyId is the Unicode version of the function. Except for the tinyid parameter, these functions behave exactly as JS_DefineProperty and JS_DefineUCProperty. See those functions for more details.

tinyid is a signed 8-bit integer that affects the id value passed to certain callbacks. Any time the JavaScript engine would pass the name of the property as a string to the id parameter of a tiny-id-aware callback, it passes INT_TO_JSVAL(tinyid) instead. The tiny-id-aware callbacks are: property getters and setters; and JSClass.addProperty, .delProperty, .getProperty, and .setProperty. Tiny ids only affect the ids passed to these hooks; the JavaScript engine does not use them as property names internally.

Tiny ids are helpful for getters and setters that are shared by several different properties. Those getters and setters can use switch (JSVAL_TO_INT(id)), instead of checking the value of id as a string, to determine which property is being accessed.

However, tiny ids can cause confusion when used with JSClass callbacks. For example, if a property named "color" is defined with tiny id 10, then the JavaScript expressions obj[10] and obj.color will both result in INT_TO_JSVAL(10) being passed to JSClass.getProperty as the id parameter. Per-property getters and setters do not suffer from this confusion: in the above example, obj.color would cause the JavaScript engine to call the getter for the color property, but obj[10] wouldn't. Traditionally, negative tiny ids are used to minimize the potential confusion, but it is best to specify a non-null getter and setter when defining a property with a tiny id.

On success, JS_DefinePropertyWithTinyId and JS_DefineUCPropertyWithTinyId return JS_TRUE. If the property already exists or cannot be created, they return JS_FALSE.

LXR ID Search for JS_DefinePropertyWithTinyId
LXR ID Search for JS_DefineUCPropertyWithTinyId