Jsctypes/api: Difference between revisions

Jsctypes/api (view source)

Revision as of 18:48, 29 September 2009

68 bytes added , 29 September 2009

→‎Proposal 2: "implicit conversion rules" --> ImplicitConvert

Jorend

638

edits

@@ Line 264: / Line 264: @@
 :'''<code>''cdata''.address()</code>''' - Return a new <code>CData</code> object of the pointer type <code>ctypes.PointerType(cdata.constructor)</code> whose value points to the C/C++ object referred to by ''cdata''.
-:'''<code>''cdata''.assign(''val'')</code>''' - Convert ''val'' to the type of ''cdata'' using the implicit conversion rules. Store the converted value in the buffer location referred to by ''cdata''.
+:'''<code>''cdata''.assign(''val'')</code>''' - Let ''cval'' = <code>ImplicitConvert(''val'', ''cdata''.constructor)</code>. If conversion fails, throw a <code>TypeError</code>. Otherwise assign the value ''cval'' to the C/C++ object referred to by ''cdata''.
 :'''<code>''cdata''.constructor</code>''' - Read-only. The type of ''cdata''. ''(Implementation note: The prototype of ''cdata'' is an object that has a read-only <code>constructor</code> property, as detailed under "minutiae".)''
@@ Line 276: / Line 276: @@
 :'''<code>''cstruct''.''member''</code>''' - Let ''F'' be a <code>CData</code> object referring to the struct member. Return <code>ConvertToJS(''F'')</code>.
-:'''<code>''cstruct''.''member'' = ''value''</code>''' - The value is converted to the type of the member using the implicit conversion rules. The converted value is stored in the buffer.
+:'''<code>''cstruct''.''member'' = ''val''</code>''' - Let ''cval'' = <code>ImplicitConvert(''val'', the type of the member)</code>. If conversion fails, throw a <code>TypeError</code>. Otherwise store ''cval'' in the appropriate member of the struct.
-:'''<code>''cstruct''.addressOfField(''name'')</code>''' - Return a new <code>CData</code> object of the appropriate pointer type, whose value points to the field of ''cstruct'' with the name ''name''. If ''name'' is not a JavaScript string or does not name a field of ''cstruct'', throw a <code>TypeError</code>.
+:'''<code>''cstruct''.addressOfField(''name'')</code>''' - Return a new <code>CData</code> object of the appropriate pointer type, whose value points to the field of ''cstruct'' with the name ''name''. If ''name'' is not a JavaScript string or does not name a member of ''cstruct'', throw a <code>TypeError</code>.
 These getters and setters can shadow the properties and methods described above.  ''(Open issue: Can they really shadow <code>.constructor</code>? Maybe <code>StructType</code> should shoot you down if you try that one.)''
@@ Line 286: / Line 286: @@
 Note that these getters and setters are only present for integers ''i'' in the range 0 &le; i &lt; <code>''carray''.length</code>.  ''(Open issue: can we arrange to throw an exception if ''i'' is out of range?)''
-:'''<code>''carray''[''i'']</code>''' - Let ''E'' be a <code>CData</code> object referring to the element at index ''i''. Return <code>ConvertToJS(''R'')</code>.
+:'''<code>''carray''[''i'']</code>''' - Let ''E'' be a <code>CData</code> object referring to the element at index ''i''. Return <code>ConvertToJS(''E'')</code>.
-:'''<code>''carray''[''i''] = ''val''</code>''' - Convert ''val'' to the type of the array element using the implicit conversion rules and store the result in the buffer.
+:'''<code>''carray''[''i''] = ''val''</code>''' - Let ''cval'' = <code>ImplicitConvert(''val'', ''carray''.elementType)</code>. If conversion fails, throw a <code>TypeError</code>. Otherwise store ''cval'' in element ''i'' of the array.
 :'''<code>''carray''.length</code>''' - Read-only. The length of the array.
@@ Line 330: / Line 330: @@
 == 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>''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.
+'''ImplicitConvert(''val'', ''t'')''' - Convert the JavaScript value ''val'' to a C/C++ value of type ''t''.  This is called 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>. This function is intended to lose precision only when there is no reasonable alternative. It generally does not coerce values of one type to another type.
-'''ImplicitConvert(''val'', ''t'')''' - Convert the JavaScript value ''val'' to a C/C++ value of type ''t''.  ''t'' may not be <code>void</code> or an array type with unspecified length. This function either returns a C/C++ value or fails. If it fails, it throws a <code>TypeError</code>.
+''t'' must not be <code>void</code> or an array type with unspecified length.
-* First, if ''val'' is a <code>CData</code> object of type ''t'', return a copy of the C/C++ object referred to by ''val''. Otherwise the behavior depends on the target type ''t''.
+* First, if ''val'' is a <code>CData</code> object of type ''t'', return the current value of the C/C++ object referred to by ''val''. Otherwise the behavior depends on the target type ''t''.
 * If ''t'' is a numeric type: