ndindex

ndarray index constructor.

In JavaScript, only strings and symbols are valid property names. When providing values for property names which are not strings or symbols, the values are serialized to strings prior to attempting to access property values. For example, the following

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

// Create an ndarray:
var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

// Define a list of indices for elements we want to retrieve from `x`:
var y = [ 0, 2 ];

// Attempt to retrieve the desired elements:
var v = x[ y ]; // => desired: <ndarray>[ 1, 3 ]
// returns undefined

is equivalent to

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );
var y = [ 0, 2 ];

var v = x[ y.toString() ];
// returns undefined

// ...which is equivalent to:
v = x[ '0,2' ];
// returns undefined

Accordingly, in order to circumvent built-in property access behavior and support non-traditional access patterns, one can leverage Proxy objects which allow one to intercept property access and to perform transformations before attempting to access elements in a target object.

To support the access pattern shown in the example above, one can leverage built-in string serialization behavior to reconstruct the original property value provided prior to serialization. The ndindex constructor described below provides one such mechanism.

Specifically, instantiated ndindex objects are assigned a unique identifier and stored in a local cache. When provided as property values to ndindex consumers, instantiated objects serialize to a string containing their unique identifier. ndindex consumers can then parse the serialized string to obtain the unique identifier and subsequently recover the original ndarray from the local cache.

Usage

var ndindex = require( '@stdlib/ndarray/index' );

ndindex( x[, options] )

Wraps a provided ndarray as an index object.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

The constructor accepts the following arguments:

x: input ndarray.
options: function options.

The constructor accepts the following options:

kind: specifies whether a provided ndarray is a specialized kind of integer input ndarray. This option is only applicable when x is an integer ndarray. Must be one of the following:
- cartesian: an ndarray containing Cartesian indices.
- linear: an ndarray containing indices representing locations in linear memory.
Default: ''.
persist: boolean indicating whether to continue persisting an index object after first usage. Default: false.

By default, an ndindex is invalidated and removed from an internal cache immediately after a consumer resolves the underlying data associated with an ndindex instance using the ndindex.get() static method. Immediate invalidation and cache removal ensures that references to the underlying ndarray data are not the source of memory leaks.

One may, however, want to reuse an ndindex instance to avoid additional memory allocation. In order to persist an ndindex and prevent automatic cache invalidation, set the persist option to true.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x, {
    'persist': true
});
// returns <ndindex>

// ...

var o = ndindex.get( idx.id );
// returns {...}

// ...

o = ndindex.get( idx.id );
// returns {...}

// ...

// Explicitly free the index object:
ndindex.free( idx.id );

In order to prevent memory leaks when working with persisted ndindex instances, one must remember to manually free persisted instances using the ndindex.free() method.

Properties

ndindex.name

String value of the ndindex constructor name.

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

ndindex.prototype.data

Read-only property returning an ndarray view of the underlying ndarray data associated with an ndindex instance.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var v = idx.data;
// returns <ndarray>

ndindex.prototype.dtype

Read-only property returning the data type of the underlying ndarray associated with an ndindex instance.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var dt = idx.dtype;
// returns 'int32'

ndindex.prototype.id

Read-only property returning the unique identifier associated with an ndindex instance.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var id = idx.id;
// returns <string>

The identifier should be used by ndindex consumers to resolve the underlying data associated with an ndindex instance.

ndindex.prototype.isCached

Read-only property returning a boolean indicating whether an ndindex instance is actively cached.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var out = idx.isCached;
// returns true

ndindex.prototype.kind

Read-only property returning the ndarray index kind.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x, {
    'kind': 'linear'
});
// returns <ndindex>

var v = idx.kind;
// returns 'linear'

The following ndarray index kinds are supported:

cartesian: an ndarray index object containing Cartesian indices.
linear: an ndarray index object for indices representing locations in linear memory.

ndindex.prototype.type

Read-only property returning the ndarray index type.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var t = idx.type;
// returns 'int'

The following ndarray index types are supported:

mask: mask ndarray, in which a value of zero indicates to include a respective element and a value of one indicates to exclude a respective element. A mask ndarray is the complement of a boolean ndarray.
bool: boolean ndarray, in which a value of true indicates to include a respective element and a value of false indicates to exclude a respective element. A boolean ndarray is the complement of a mask ndarray.
int: integer ndarray, in which each element is an index indicating the position of an element to include. Elements are not required to be unique (i.e., more than element may resolve to the same position).

Methods

ndindex.free( id )

Frees the ndindex associated with a provided identifier.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x, {
    'persist': true
});
// returns <ndindex>

// ...

var out = ndindex.free( idx.id );
// returns true

Once an ndindex is freed, the instance is invalid and can no longer be used. Any subsequent ndindex operations (i.e., property and method access) will raise an exception.

ndindex.get( id )

Returns the ndarray associated with the ndindex having a provided identifier.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x, {
    'persist': true
});
// returns <ndindex>

// ...

var o = ndindex.get( idx.id );
// returns {...}

var d = o.data;
// returns <ndarray>

var t = o.type;
// returns 'int'

var dt = o.dtype;
// returns 'int32'

The returned object has the following properties:

data: the underlying "base" ndarray view associated with the ndindex identified by the provided id.
type: the type of ndarray index. One of the following: 'int', 'bool', or 'mask'.
kind: the ndarray index "kind". One of the following: '', 'cartesian', or 'linear'.
dtype: the data type of the underlying ndarray.

If the ndindex associated with a provided identifier was not explicitly persisted, calling this method will cause the ndindex to be invalidated and removed from an internal cache. Any subsequent instance operations (i.e., property and method access) will raise an exception.

ndindex.cartesianIndex( x[, options] )

Wraps a provided ndarray as a Cartesian index object.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ), {
    'shape': [ 2, 2 ]
});

var idx = ndindex.cartesianIndex( x );
// returns <ndindex>

This method is a convenience method for creating an ndindex with the kind option set to 'cartesian'. The function accepts the same arguments and options as ndindex above.

ndindex.linearIndex( x[, options] )

Wraps a provided ndarray as a linear index object.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = ndindex.linearIndex( x );
// returns <ndindex>

This method is a convenience method for creating an ndindex with the kind option set to 'linear'. The function accepts the same arguments and options as ndindex above.

ndindex.prototype.toString()

Serializes an ndindex as a string.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var str = idx.toString();
// e.g., 'ndindex<0>'

An ndindex is intended to be an opaque object used by objects supporting "fancy" indexing (e.g., fancy ndarrays). As such, when serialized as a string, a serialized ndindex includes only the unique identifier associated with the respective instance.

ndindex.prototype.toJSON()

Serializes an ndindex as a JSON object.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );
// returns <ndindex>

var o = idx.toJSON();
// returns { 'type': 'ndindex', 'kind': '', 'data': { ... } }

JSON.stringify() implicitly calls this method when stringifying an ndindex instance.

Notes

ndindex instances have no explicit functionality; however, they are used by "fancy" ndarrays and other packages for element retrieval and assignment.
Because ndindex instances leverage an internal cache implementing the singleton pattern, one must be sure to use the same ndindex constructor as ndindex consumers. If one uses a different ndindex constructor, the consumer will not be able to resolve an ndarray view of the original ndarray, as the consumer will attempt to resolve an ndindex instance in the wrong internal cache.

Because non-persisted ndindex instances are freed after first use, in order to avoid holding onto memory and to allow garbage collection, one should avoid scenarios in which an ndindex is never used. For example,

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );

var o;
if ( x.get( 0 ) === 0 ) {
    // Do something with `idx`...
    o = ndindex.get( idx.id );

    // ...
}

will leak memory as idx is only consumed within an if block which never evaluates. In such scenarios, one should either refactor to avoid inadvertently holding onto memory or explicitly free the ndindex.

var array = require( '@stdlib/ndarray/array' );
var Int32Array = require( '@stdlib/array/int32' );

var x = array( new Int32Array( [ 1, 2, 3, 4 ] ) );

var idx = new ndindex( x );

var o;
if ( x.get( 0 ) === 0 ) {
    // Do something with `idx`...
    o = ndindex.get( idx.id );

    // ...
} else {
    ndindex.free( idx.id );
}

Examples

var empty = require( '@stdlib/ndarray/empty' );
var ndindex = require( '@stdlib/ndarray/index' );

var x = empty( [ 5 ], {
    'dtype': 'uint8'
});
var i = new ndindex( x );
// returns <ndindex>

var o = ndindex.get( i.id );
// returns {...}

console.log( 'Type: %s. Data type: %s.', o.type, o.dtype );

x = empty( [ 5 ], {
    'dtype': 'generic'
});
i = new ndindex( x );
// returns <ndindex>

o = ndindex.get( i.id );
// returns {...}

console.log( 'Type: %s. Data type: %s.', o.type, o.dtype );

x = empty( [ 5 ], {
    'dtype': 'bool'
});
i = new ndindex( x );
// returns <ndindex>

o = ndindex.get( i.id );
// returns {...}

console.log( 'Type: %s. Data type: %s.', o.type, o.dtype );

x = empty( [ 5 ], {
    'dtype': 'int32'
});
i = new ndindex( x );
// returns <ndindex>

o = ndindex.get( i.id );
// returns {...}

console.log( 'Type: %s. Data type: %s.', o.type, o.dtype );