Working with data

  • Revision slug: Mozilla/js-ctypes/Using_js-ctypes/Working_with_data
  • Revision title: Working with data
  • Revision id: 98263
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment 2 words added

Revision Content

{{ gecko_minversion_header("1.9.3") }}{{ draft() }}

Creating CData objects

Data types for use with js-ctypes are represented by CType objects. These are JavaScript constructors; as such, they're callable functions that you can use to create new CData objects of that type. There are several ways you can go about creating new CData objects.

Creating uninitialized CData objects

There are three forms of the syntax for creating CData objects without immediately assigning them a value:

var myCDataObj = new type;

var myCDataObj = new type();

var myCDataObj = type();

These all do the same thing: they return a new CData object of the specified type, whose data buffer has been populated entirely with zeroes.

Note: If type.size is undefined, creating a new object this way will throw a TypeError exception.

Creating initialized CData objects

Similarly, you can initialize CData objects with specific values at the type of creation by specifying them as a parameter when calling the CType's constructor, like this:

var myCDataObj = new type(value);

var myCDataObj = type(value);

If the size of the specified type isn't undefined, the specified value is converted to the given type. If the conversion isn't possible, TypeError is thrown. The resulting data is then copied into a new CData object. If the original value is already a CData object, the original object is simply duplicated directly into the new one.

If type is an array type of unspecified length, the following steps are taken:

  • If the value is a size value, a new array of that length is created, with its cells ready to accept values of the same type as those in the specified array. This is the same as new ArrayType(type.elementType, value).
  • If the type represents a JavaScript string (that is, an array of jschar characters followed by a null terminator), a copy of that string is created and returned.
  • If the type is an array of 8-bit characters and value is a UTF-16 string, the new CData object is the result of converting the UTF-16 string to UTF-8, with a null terminator.
  • If the value is a JavaScript array object and it has a non-negative length, a new array is created and the contents of the array specified by value are converted to CData objects and copied into the new array, which is then returned.
  • If none of these conditions are met, a TypeError is thrown.

If type is ctypes.void_t, a TypeError is thrown.

Example: Creating an array

let arrayType = ctypes.ArrayType(ctypes.int32_t);
let myArray = new arrayType(5); 

At this point, myArray.length is 5; there are 5 entries in the array. myArray.constructor.size is 20; the total size of the array's data buffer is 20 bytes (5 entries, 4 bytes apiece).

Type casting

You can type cast data from one type to another by using the ctypes.cast() function:

var newObj = ctypes.cast(origObj, newType);

This will return a new object whose data block is shared with the original object, but whose type is newType. If the size of the new type is undefined or larger than the size of the original object's data block, TypeError is thrown.

This works very much like a standard C type cast or C++ reinterpret_cast.

Objects can share memory

It's important to keep in mind that two (or more) CData objects can share the same memory block for their contents. This will happen, for example, when type casting. This is called aliasing. The shared memory can be whole or in part.

For example:

const Point = new ctypes.StructType("Point", [[ctypes.int32_t, 'x'], [ctypes.int32_t, 'y']]);
const Rect = new ctypes.StructType("Rect", [[Point, 'topLeft'], [Point, 'bottomRight']]);

var r = Rect();
var p = r.topLeft;
r.topLeft.x = 100; 

At this point, p is a reference to the topLeft field in the Rect named r. Setting the value of p.x will affect the value of r.topLeft.x, as expected.

Quirks in equality

Equality doesn't work the same way in JavaScript as it does in C, which means certain operations might not work the way you expect. In particular, comparing two different objects that are represented under-the-hood as JavaScript objects using the == or === operators will always return false. This affects comparisons of pointers, integers that are the same size as pointers, and 64-bit integers.

More information coming soon.

64-bit integers

While most numeric types in js-ctypes are represented by standard JavaScript Number objects, 64-bit integers cannot all be represented accurately by this type. For that reason, 64-bit and pointer-sized C values of numeric types don't get automatically converted to JavaScript numbers. Instead, they're converted to JavaScript objects of the type ctypes.Int64 and ctypes.UInt64.

Because these aren't standard numeric types, you can't use arithmetic operators on them. Instead, you'll have to use the provided convenience functions.

Note: These 64-bit integer types are intentionally low on features, so that when JavaScript adds a "big number" type, we can easily upgrade to support that properly.

See also

Revision Source

<p>{{ gecko_minversion_header("1.9.3") }}{{ draft() }}</p>
<h2>Creating CData objects</h2>
<p>Data types for use with js-ctypes are represented by <a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a> objects. These are JavaScript constructors; as such, they're callable functions that you can use to create new <a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData"><code>CData</code></a> objects of that type. There are several ways you can go about creating new <code>CData</code> objects.</p>
<h3>Creating uninitialized CData objects</h3>
<p>There are three forms of the syntax for creating <code>CData</code> objects without immediately assigning them a value:</p>
<p><code>var myCDataObj = new <em>type</em>;</code></p>
<p><code>var myCDataObj = new <em>type</em>();</code></p>
<p><code>var myCDataObj = <em>type</em>();</code></p>
<p>These all do the same thing: they return a new <code>CData</code> object of the specified type, whose data buffer has been populated entirely with zeroes.</p>
<div class="note"><strong>Note:</strong> If <code><em>type</em>.size</code> is undefined, creating a new object this way will throw a <code>TypeError</code> exception.</div>
<h3>Creating initialized CData objects</h3>
<p>Similarly, you can initialize <code>CData</code> objects with specific values at the type of creation by specifying them as a parameter when calling the <a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a>'s constructor, like this:</p>
<p><code>var myCDataObj = new <em>type</em>(<em>value</em>);</code></p>
<p><code>var myCDataObj = <em>type</em>(<em>value</em>);</code></p>
<p>If the size of the specified type isn't undefined, the specified value is converted to the given type. If the conversion isn't possible, <code>TypeError</code> is thrown. The resulting data is then copied into a new <code>CData</code> object. If the original value is already a <code>CData</code> object, the original object is simply duplicated directly into the new one.</p>
<p>If <em><code>type</code></em> is an array type of unspecified length, the following steps are taken:</p>
<ul> <li>If the <code><em>value</em></code> is a size value, a new array of that length is created, with its cells ready to accept values of the same type as those in the specified array. This is the same as <code>new ArrayType(<em>type</em>.elementType, <em>value</em>)</code>.</li> <li>If the <em><code>type</code></em> represents a JavaScript string (that is, an array of jschar characters followed by a null terminator), a copy of that string is created and returned.</li> <li>If the <em><code>type</code></em> is an array of 8-bit characters and <em><code>value</code></em> is a UTF-16 string, the new <code>CData</code> object is the result of converting the UTF-16 string to UTF-8, with a null terminator.</li> <li>If the <code><em>value</em></code> is a JavaScript array object and it has a non-negative length, a new array is created and the contents of the array specified by <code><em>value</em></code> are converted to <code>CData</code> objects and copied into the new array, which is then returned.</li> <li>If none of these conditions are met, a <code>TypeError</code> is thrown.</li>
</ul>
<p>If <em><code>type</code></em> is <code>ctypes.void_t</code>, a <code>TypeError</code> is thrown.</p>
<h4>Example: Creating an array</h4>
<pre class="brush: js">let arrayType = ctypes.ArrayType(ctypes.int32_t);
let myArray = new arrayType(5); 
</pre>
<p>At this point, <code>myArray.length</code> is 5; there are 5 entries in the array. <code>myArray.constructor.size</code> is 20; the total size of the array's data buffer is 20 bytes (5 entries, 4 bytes apiece).</p><h2>Type casting</h2>
<p>You can type cast data from one type to another by using the <code>ctypes.cast()</code> function:</p>
<p><code>var newObj = ctypes.cast(<em>origObj</em>, <em>newType</em>);</code></p>
<p>This will return a new object whose data block is shared with the original object, but whose type is <code><em>newType</em></code>. If the size of the new type is undefined or larger than the size of the original object's data block, <code>TypeError</code> is thrown.</p>
<p>This works very much like a standard C type cast or C++ <code>reinterpret_cast</code>.</p>
<h2>Objects can share memory</h2>
<p>It's important to keep in mind that two (or more) <code>CData</code> objects can share the same memory block for their contents. This will happen, for example, when <a href="/en/js-ctypes/Using_js-ctypes/Working_with_data#Type_casting" title="en/js-ctypes/Using js-ctypes/Working with data#Type casting">type casting</a>. This is called <strong>aliasing</strong>. The shared memory can be whole or in part.</p>
<p>For example:</p>
<pre class="brush: js">const Point = new ctypes.StructType("Point", [[ctypes.int32_t, 'x'], [ctypes.int32_t, 'y']]);
const Rect = new ctypes.StructType("Rect", [[Point, 'topLeft'], [Point, 'bottomRight']]);

var r = Rect();
var p = r.topLeft;
r.topLeft.x = 100; 
</pre>
<p>At this point, <code>p</code> is a reference to the <code>topLeft</code> field in the <code>Rect</code> named <code>r</code>. Setting the value of <code>p.x</code> will affect the value of <code>r.topLeft.x</code>, as expected.</p>
<h2>Quirks in equality</h2>
<p>Equality doesn't work the same way in JavaScript as it does in C, which means certain operations might not work the way you expect. In particular, comparing two different objects that are represented under-the-hood as JavaScript objects using the <code>==</code> or <code>===</code> operators will always return <code>false</code>. This affects comparisons of pointers, integers that are the same size as pointers, and 64-bit integers.</p>
<p><em>More information coming soon.</em></p>
<h2>64-bit integers</h2>
<p>While most numeric types in js-ctypes are represented by standard JavaScript <a href="/cn/Core_JavaScript_1.5_Reference/Global_Objects/Number" title="cn/Core JavaScript 1.5 Reference/Global Objects/Number"><code>Number</code></a> objects, 64-bit integers cannot all be represented accurately by this type. For that reason, 64-bit and pointer-sized C values of numeric types don't get automatically converted to JavaScript numbers. Instead, they're converted to JavaScript objects of the type <code>ctypes.Int64</code> and <code>ctypes.UInt64</code>.</p>
<p>Because these aren't standard numeric types, you can't use arithmetic operators on them. Instead, you'll have to use the provided convenience functions.</p>
<div class="note"><strong>Note:</strong> These 64-bit integer types are intentionally low on features, so that when JavaScript adds a "big number" type, we can easily upgrade to support that properly.</div>
<h2>See also</h2>
<ul> <li><code><a href="/en/js-ctypes/js-ctypes_reference/CData" title="en/js-ctypes/js-ctypes reference/CData">CData</a><br> </code></li> <li><a href="/en/js-ctypes/js-ctypes_reference/CType" title="en/js-ctypes/js-ctypes reference/CType"><code>CType</code></a></li>
</ul>
Revert to this revision