structFactory

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

Installation

npm install @stdlib/array-struct-factory

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

Notice

This package is part of stdlib, a standard library for JavaScript and Node.js, with an emphasis on numerical and scientific computing. The library provides a collection of robust, high performance libraries for mathematics, statistics, streams, utilities, and more.

For more information on the project, filing bug reports and feature requests, and guidance on how to develop stdlib, see the main project repository.

Community

License

See LICENSE.

Copyright

Copyright © 2016-2026. The Stdlib Authors.