JSConversions: A general system of converting between native objects and their JavaScript representations

implemented by MarkT; documented by janwas.

note: "native" denotes C++ types/values, as opposed to JS objects that wrap them.

ToNative/ToScript

• Overview:
  • Converts C++ JSObject-derived class pointers to and from JSObject*.
• Syntax:
  • template<typename T> T* ToNative( JSContext* cx, JSObject* obj );
  • template<typename T> T* ToNative( jsval v );
  • template<typename T> JSObject* ToScript( T* Native );
  • Example: CDamageType* dmg = ToNative<CDamageType>( argv[0] );
• Parameters:
  • ToNative: optionally either JSContext* and JSObject*, or jsval (useful for converting argv[i])
  • ToScript: C++ class pointer
• Returns:
  • The C++ class pointer resp. JS object pointer.
• Notes:

ToPrimitive/ToJSVal

• Overview:
  • Converts C++ built-in types or classes (if the requisite specialization exists) to and from jsval.
• Syntax:
  • template<typename T> bool ToPrimitive( JSContext* cx, jsval v, T& Storage );
  • template<typename T> bool ToPrimitive( JSContext* cx, jsval v, T*& Storage );
  • template<typename T> inline T ToPrimitive( JSContext* cx, jsval v );
  • template<typename T> inline T ToPrimitive( jsval v );
  • template<typename T> jsval ToJSVal( T& Native );
  • template<typename T> jsval ToJSVal( T*& Native );
  • template<typename T> jsval ToJSVal( const T& Native );
  • Example: ToPrimitive<float>( cx, argv[0], gain);
• Parameters:
  • ToPrimitive: the script context (if desired); value to convert and destination.
  • ToScript: the C++ value to convert.
• Returns:
  • bool to indicate success resp. resulting JS value.
• Notes:
  • The T*& calls automatically dereference pointers-to-objects.

JSParseString

• Overview:
  • Converts textual representation to jsval.
• Syntax:
  • jsval JSParseString( const CStrW& Native );
  • Example: AddProperty( PropertyName, JSParseString( ValueString ) );
• Parameters:
  • CStrW string holding a simple value (no expressions are permitted)
• Returns:
  • The converted value.
• Notes:
  • Does not perform any evaluation; merely converts text to jsval.