638
edits
Jsctypes/api: Difference between revisions
Jump to navigation
Jump to search
→Conversions: "reference" -> "CData object" continued
(→Conversions: "reference" -> "CData object" continued) |
|||
| Line 298: | Line 298: | ||
== Conversions == | == Conversions == | ||
The '''implicit conversion rules''' are applied whenever a JavaScript value of any kind is passed to a parameter of a ctypes-declared function, passed to <code>'' | The '''implicit conversion rules''' are applied whenever a JavaScript value of any kind is passed to a parameter of a ctypes-declared function, passed to <code>''cdata''.assign(''val'')</code>, or assigned to an array element or struct member, as in <code>''carray''[''i''] = ''val''</code> or <code>''cstruct''.''member'' = ''val''</code>. These rules are intended to lose precision only when there is no reasonable alternative. They generally do not coerce values of one type to another type. | ||
''(TODO: precise rules.)'' | ''(TODO: precise rules. Some of the properties we're shooting for here are: if val is a CData object of the right type, return its C/C++ value; applying the rules to a JS number is exactly the same as applying them to the corresponding C/C++ double; applying the rules to a JS boolean is exactly the same as applying them to the corresponding C/C++ bool; plain old JS Objects can implicitly convert to C/C++ structs; plain old JS Arrays can implicitly convert to C/C++ arrays.)'' | ||
The '''explicit conversion rules''' are applied when a JavaScript value is passed as a parameter when calling a type, as in <code>''t''(''val'')</code> or <code>new ''t''(''val'')</code>. These rules are a bit more aggressive. | The '''explicit conversion rules''' are applied when a JavaScript value is passed as a parameter when calling a type, as in <code>''t''(''val'')</code> or <code>new ''t''(''val'')</code>. These rules are a bit more aggressive. | ||
''(TODO: precise rules.)'' | ''(TODO: precise rules. Properties we're shooting for: if implicit conversion produces a result, explicit conversion produces the same result; in some but not all cases where a C++ ''typename(value)'' function-like cast expression would work, explicit conversion also works.)'' | ||
'''<code>ConvertToJS(''x'')</code>''' - This function is used to convert a | '''<code>ConvertToJS(''x'')</code>''' - This function is used to convert a <code>CData</code> object or a C/C++ return value to a JavaScript value. The intent is to return a simple JavaScript value whenever possible, and a <code>CData</code> object otherwise. The precise rules are: | ||
* If the value is of type <code>void</code>, return <code>undefined</code>. | * If the value is of type <code>void</code>, return <code>undefined</code>. | ||
| Line 312: | Line 312: | ||
* If the value is of type <code>bool</code>, return the corresponding JavaScript boolean. | * If the value is of type <code>bool</code>, return the corresponding JavaScript boolean. | ||
* If the value is of a number type | * If the value is of a number type other than the pointer-sized types and the 64-bit types, return the corresponding JavaScript number. | ||
* If the value is | * If the value is of a string type and null, return <code>null</code>. | ||
* If the value is of a string type and non-null, return a JavaScript string. | * If the value is of a string type and non-null, return a JavaScript string. | ||
* | * Otherwise the value is of an array, struct, or pointer type. If the argument ''x'' is already a <code>CData</code> object, return it. Otherwise allocate a new buffer of the appropriate size, populate it with the C/C++ value ''x'', and return a ctypes reference to the complete object in the new buffer. | ||
Note that we do not autoconvert null C/C++ pointers to the JavaScript <code>null</code> value. | |||
== Examples == | == Examples == | ||