structFactory

Return a constructor for creating arrays having a fixed-width composite data type.

Usage

var structFactory = require( '@stdlib/array/struct-factory' );

structFactory( arg )

Returns a constructor for creating arrays having a fixed-width composite data type.

var schema = [
    {
        'name': 'beep',
        'type': 'float64'
    },
    {
        'name': 'boop',
        'type': 'int32'
    }
];
var StructArray = structFactory( schema );
// returns <Function>

The function supports the following parameters:

• arg: struct constructor or a struct schema.

---

Array Constructor

StructArray()

TODO: add documentation of constructor

---

Array Properties

StructArray.BYTES_PER_ELEMENT

Number of bytes per view element.

var schema = [
    {
        'name': 'foo',
        'type': 'bool'
    }
];
var StructArray = structFactory( schema );

var nbytes = StructArray.BYTES_PER_ELEMENT;
// returns 1

StructArray.name

Array constructor name.

var schema = [
    {
        'name': 'foo',
        'type': 'bool'
    }
];
var StructArray = structFactory( schema );

var str = StructArray.name;
// returns 'StructArray'

StructArray.prototype.buffer

Read-only property which returns the ArrayBuffer referenced by the array.

var schema = [
    {
        'name': 'foo',
        'type': 'bool'
    }
];
var StructArray = structFactory( schema );

var arr = new StructArray( 5 );
var buf = arr.buffer;
// returns <ArrayBuffer>

StructArray.prototype.byteLength

Read-only property which returns the length (in bytes) of the array.

var schema = [
    {
        'name': 'foo',
        'type': 'int32'
    }
];
var StructArray = structFactory( schema );

var arr = new StructArray( 5 );
var byteLength = arr.byteLength;
// returns 20

StructArray.prototype.byteOffset

Read-only property which returns the offset (in bytes) of the array from the start of its ArrayBuffer.

var schema = [
    {
        'name': 'foo',
        'type': 'bool'
    }
];
var StructArray = structFactory( schema );

var arr = new StructArray( 5 );
var byteOffset = arr.byteOffset;
// returns 0

StructArray.prototype.BYTES_PER_ELEMENT

Number of bytes per view element.

var schema = [
    {
        'name': 'foo',
        'type': 'bool'
    }
];
var StructArray = structFactory( schema );

var arr = new StructArray( 5 );
var nbytes = arr.BYTES_PER_ELEMENT;
// returns 1

StructArray.prototype.length

Read-only property which returns the number of view elements.

var schema = [
    {
        'name': 'foo',
        'type': 'bool'
    }
];
var StructArray = structFactory( schema );

var arr = new StructArray( 5 );
var len = arr.length;
// returns 5

---

Array Methods

TODO: document methods

---

Notes

• While returned constructors strive to maintain (but do not guarantee) consistency with typed arrays, significant deviations from ECMAScript-defined typed array behavior are as follows:

  • Constructors do not require the new operator.
  • Accessing array elements using bracket syntax (e.g., X[i]) is not supported. Instead, one must use the .get() method.
  • Accessed array elements are a view on underlying memory. Thus, mutation of accessed elements mutates the underlying buffer.

• Struct arrays share several similarities with generic arrays containing objects (e.g., nested property access); however, the principal difference is that struct arrays are strongly typed and backed by fixed memory. Struct arrays are particularly well-suited for zero-copy transfer of data stored in composite data types when interoperating between JavaScript and C.

Examples

var factory = require( '@stdlib/array/struct-factory' );

// Define a schema for a composite data type for storing a student's test scores:
var schema = [
    {
        'name': 'test_number',
        'type': 'int16'
    },
    {
        'name': 'pass',
        'type': 'bool'
    },
    {
        'name': 'correct',
        'type': 'int32'
    },
    {
        'name': 'incorrect',
        'type': 'int32'
    },
    {
        'name': 'percentage',
        'type': 'float32'
    }
];

// Create an array constructor for creating composite data type arrays:
var TestScoreArray = factory( schema );
console.log( 'Layout: %s', TestScoreArray.struct.layout );

// Create a new array for storing test scores:
var student1 = new TestScoreArray( 10 );
console.log( 'Byte length: %d', student1.byteLength );