Working with data

  • Revision slug: Mozilla/js-ctypes/Using_js-ctypes/Working_with_data
  • Revision title: Working with data
  • Revision id: 98258
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment add see also; 4 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 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).

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>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>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