638
edits
Jsctypes/api: Difference between revisions
new jargon "wrapped integer type"; delete leftover reference to uint32_t possibly aliasing unsigned long (we decided against it)
(→Conversions: kill the voidptr_t("0x0123456789abcdef") ExplicitConvert case) |
(new jargon "wrapped integer type"; delete leftover reference to uint32_t possibly aliasing unsigned long (we decided against it)) |
||
| Line 29: | Line 29: | ||
:Since some 64-bit values are outside the range of the JavaScript number type, <code>ctypes.int64_t</code> and <code>ctypes.uint64_t</code> do not autoconvert to JavaScript numbers. Instead, they convert to objects of the wrapper types <code>ctypes.Int64</code> and <code>ctypes.UInt64</code> (which are JavaScript object types, not <code>CType</code>s). See "64-bit integer objects" below. | :Since some 64-bit values are outside the range of the JavaScript number type, <code>ctypes.int64_t</code> and <code>ctypes.uint64_t</code> do not autoconvert to JavaScript numbers. Instead, they convert to objects of the wrapper types <code>ctypes.Int64</code> and <code>ctypes.UInt64</code> (which are JavaScript object types, not <code>CType</code>s). See "64-bit integer objects" below. | ||
:'''<code>ctypes.size_t, ssize_t, intptr_t, uintptr_t</code>''' - Primitive types whose size depends on the platform. These types do not autoconvert to JavaScript numbers | :'''<code>ctypes.size_t, ssize_t, intptr_t, uintptr_t</code>''' - Primitive types whose size depends on the platform. ''(These types do not autoconvert to JavaScript numbers. Instead they convert to wrapper objects, even on 32-bit platforms. See "64-bit integer objects" below. Rationale: On 64-bit platforms, there are values of these types that cannot be precisely represented as JS numbers. It will be easier to write code that works on multiple platforms if the builtin types autoconvert in the same way on all platforms.)'' | ||
:'''<code>ctypes.bool, short, unsigned_short, int, unsigned, unsigned_int, long, unsigned_long, float, double</code>''' - Types that behave like the corresponding C types. As in C, <code>unsigned</code> is always an alias for <code>unsigned_int</code>. | :'''<code>ctypes.bool, short, unsigned_short, int, unsigned, unsigned_int, long, unsigned_long, float, double</code>''' - Types that behave like the corresponding C types. As in C, <code>unsigned</code> is always an alias for <code>unsigned_int</code>. | ||
:<code>ctypes.long</code> and <code>ctypes.unsigned_long</code> autoconvert to 64-bit integer objects | :''(<code>ctypes.long</code> and <code>ctypes.unsigned_long</code> autoconvert to 64-bit integer objects on all platforms. The rest autoconvert to JavaScript numbers. Rationale: Some platforms have 64-bit <code>long</code> and some do not.)'' | ||
:'''<code>ctypes.char, ctypes.signed_char, ctypes.unsigned_char</code>''' - Character types that behave like the corresponding C types. (These are distinct from <code>int8_t</code> and <code>uint8_t</code> in details of conversion behavior. For example, js-ctypes autoconverts between C characters and one-character JavaScript strings.) | :'''<code>ctypes.char, ctypes.signed_char, ctypes.unsigned_char</code>''' - Character types that behave like the corresponding C types. (These are distinct from <code>int8_t</code> and <code>uint8_t</code> in details of conversion behavior. For example, js-ctypes autoconverts between C characters and one-character JavaScript strings.) | ||
| Line 42: | Line 42: | ||
:'''<code>ctypes.voidptr_t</code>''' - The C type <code>void *</code>. | :'''<code>ctypes.voidptr_t</code>''' - The C type <code>void *</code>. | ||
The ''wrapped integer types'' are the types <code>int64_t</code>, <code>uint64_t</code>, <code>size_t</code>, <code>ssize_t</code>, <code>intptr_t</code>, <code>uintptr_t</code>, <code>long</code>, and <code>unsigned_long</code>. These are the types that autoconvert to 64-bit integer objects rather than to primitive JavaScript numbers. | |||
== User-defined types == | == User-defined types == | ||
| Line 89: | Line 91: | ||
:'''<code>''t''.name</code>''' - A string, the type's name. It's intended that in ordinary use, this will be a C/C++ type expression, but it's not really meant to be machine-readable in all cases. | :'''<code>''t''.name</code>''' - A string, the type's name. It's intended that in ordinary use, this will be a C/C++ type expression, but it's not really meant to be machine-readable in all cases. | ||
:For primitive types this is just the name of the corresponding C/C++ type. | :For primitive types this is just the name of the corresponding C/C++ type. | ||
:For struct types and opaque pointer types, this is simply the string that was passed to the constructor. For other pointer types and array types this should try to generate valid C/C++ type expressions, which isn't exactly trivial. | :For struct types and opaque pointer types, this is simply the string that was passed to the constructor. For other pointer types and array types this should try to generate valid C/C++ type expressions, which isn't exactly trivial. | ||
| Line 371: | Line 373: | ||
* If the type of ''x'' is <code>bool</code>, return the corresponding JavaScript boolean. | * If the type of ''x'' is <code>bool</code>, return the corresponding JavaScript boolean. | ||
* If ''x'' is of a number type | * If ''x'' is of a number type but not a wrapped integer type, return the corresponding JavaScript number. | ||
* If ''x'' is | * If ''x'' is a signed wrapped integer type (<code>long</code>, <code>int64_t</code>, <code>ssize_t</code>, or <code>intptr_t</code>), return a <code>ctypes.Int64</code> object with value ''x''. | ||
* If ''x'' is | * If ''x'' is an unsigned wrapped integer type (<code>unsigned long</code>, <code>uint64_t</code>, <code>size_t</code>, or <code>uintptr_t</code>), return a <code>ctypes.UInt64</code> object with value ''x''. | ||
* If ''x'' is of type <code>jschar</code>, return a JavaScript string of length 1 containing the value of ''x'' (like <code>String.fromCharCode(x)</code>). | * If ''x'' is of type <code>jschar</code>, return a JavaScript string of length 1 containing the value of ''x'' (like <code>String.fromCharCode(x)</code>). | ||
| Line 462: | Line 464: | ||
* If ''t'' is a pointer type and ''val'' is a number, <code>Int64</code> object, or <code>UInt64</code> object that can be exactly represented as an <code>intptr_t</code> or <code>uintptr_t</code>, the result is the same as casting that <code>intptr_t</code> or <code>uintptr_t</code> value to type ''t'' with a C-style cast. | * If ''t'' is a pointer type and ''val'' is a number, <code>Int64</code> object, or <code>UInt64</code> object that can be exactly represented as an <code>intptr_t</code> or <code>uintptr_t</code>, the result is the same as casting that <code>intptr_t</code> or <code>uintptr_t</code> value to type ''t'' with a C-style cast. | ||
* If ''t'' is a | * If ''t'' is a wrapped integer type, and ''val'' is a string consisting entirely of an optional minus sign, followed by the characters "0x" or "0X", followed by one or more hexadecimal digits, then the result is the same as casting the number named by ''val'' to type ''t'' with a C-style cast. | ||
* Otherwise fail. | * Otherwise fail. | ||