ndindex

About stdlib...

We believe in a future in which the web is a preferred environment for numerical computation. To help realize this future, we've built stdlib. stdlib is a standard library, with an emphasis on numerical and scientific computation, written in JavaScript (and C) for execution in browsers and in Node.js.

The library is fully decomposable, being architected in such a way that you can swap out and mix and match APIs and functionality to cater to your exact preferences and use cases.

When you use stdlib, you can be absolutely certain that you are using the most thorough, rigorous, well-written, studied, documented, tested, measured, and high-quality code out there.

To join us in bringing numerical computing to the web, get started by checking us out on GitHub, and please consider financially supporting stdlib. We greatly appreciate your continued support!

ndindex

ndarray index constructor.

In JavaScript, only strings and symbols are valid property names. When providing values for property names which are not string 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.

Installation

npm install @stdlib/ndarray-index

Alternatively,

To load the package in a website via a script tag without installation and bundlers, use the ES Module available on the esm branch (see README).
If you are using Deno, visit the deno branch (see README for usage intructions).
For use in Observable, or in browser/node environments, use the Universal Module Definition (UMD) build available on the umd branch (see README).

The branches.md file summarizes the available branches and displays a diagram illustrating their relationships.

To view installation and usage instructions specific to each branch build, be sure to explicitly navigate to the respective README files on each branch, as linked to above.

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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
.github		.github
benchmark		benchmark
dist		dist
docs		docs
examples		examples
lib		lib
test		test
.editorconfig		.editorconfig
.eslintrc.js		.eslintrc.js
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmignore		.npmignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
CONTRIBUTORS		CONTRIBUTORS
LICENSE		LICENSE
Makefile		Makefile
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
branches.md		branches.md
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ndindex

Installation

Usage

ndindex( x[, options] )

Properties

ndindex.name

ndindex.prototype.data

ndindex.prototype.dtype

ndindex.prototype.id

ndindex.prototype.isCached

ndindex.prototype.kind

ndindex.prototype.type

Methods

ndindex.free( id )

ndindex.get( id )

ndindex.cartesianIndex( x[, options] )

ndindex.linearIndex( x[, options] )

ndindex.prototype.toString()

ndindex.prototype.toJSON()

Notes

Examples

Notice

Community

License

Copyright

About

Releases

Sponsor this project

Packages

Languages

License

stdlib-js/ndarray-index

Folders and files

Latest commit

History

Repository files navigation

ndindex

Installation

Usage

ndindex( x[, options] )

Properties

ndindex.name

ndindex.prototype.data

ndindex.prototype.dtype

ndindex.prototype.id

ndindex.prototype.isCached

ndindex.prototype.kind

ndindex.prototype.type

Methods

ndindex.free( id )

ndindex.get( id )

ndindex.cartesianIndex( x[, options] )

ndindex.linearIndex( x[, options] )

ndindex.prototype.toString()

ndindex.prototype.toJSON()

Notes

Examples

Notice

Community

License

Copyright

About

Topics

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages 0

Languages

Packages