diff --git a/index/docs/types/index.d.ts b/index/docs/types/index.d.ts index 99140fe8..6acd4a10 100644 --- a/index/docs/types/index.d.ts +++ b/index/docs/types/index.d.ts @@ -20,22 +20,7 @@ /// -import { Collection, AccessorArrayLike, DataType } from '@stdlib/types/array'; - -/** -* Boolean index array. -*/ -type BooleanIndexArray = Collection | AccessorArrayLike; - -/** -* Integer index array. -*/ -type IntegerIndexArray = Collection | AccessorArrayLike; - -/** -* Index array. -*/ -type IndexArray = BooleanIndexArray | IntegerIndexArray; +import { BooleanIndexArray, IntegerIndexArray, IndexArray, MaskArrayIndex, Int32ArrayIndex, BooleanArrayIndex, IntegerArrayIndex, ArrayIndex, BaseIndexArrayObject, IndexArrayObject } from '@stdlib/types/array'; /** * Interface describing function options. @@ -47,242 +32,6 @@ interface Options { persist?: boolean; } -/** -* Interface describing an object containing array index data. -*/ -interface BaseArrayObject { - /** - * The underlying array associated with an array index. - */ - data: IndexArray; - - /** - * The type of array index. - */ - type: 'int' | 'bool' | 'mask'; - - /** - * The data type of the underlying array. - */ - dtype: DataType; -} - -/** -* Interface describing an object containing mask array data. -*/ -interface MaskArrayObject extends BaseArrayObject { - /** - * The underlying array associated with an array index. - */ - data: Uint8Array; - - /** - * The type of array index. - */ - type: 'mask'; - - /** - * The data type of the underlying array. - */ - dtype: 'uint8'; -} - -/** -* Interface describing an object containing integer array data. -*/ -interface Int32ArrayObject extends BaseArrayObject { - /** - * The underlying array associated with an array index. - */ - data: Int32Array; - - /** - * The type of array index. - */ - type: 'int'; - - /** - * The data type of the underlying array. - */ - dtype: 'int32'; -} - -/** -* Interface describing an object containing integer array data. -*/ -interface IntegerArrayObject extends BaseArrayObject { - /** - * The underlying array associated with an array index. - */ - data: IntegerIndexArray; - - /** - * The type of array index. - */ - type: 'int'; - - /** - * The data type of the underlying array. - */ - dtype: 'generic'; -} - -/** -* Interface describing an object containing boolean array data. -*/ -interface BooleanArrayObject extends BaseArrayObject { - /** - * The underlying array associated with an array index. - */ - data: BooleanIndexArray; - - /** - * The type of array index. - */ - type: 'bool'; - - /** - * The data type of the underlying array. - */ - dtype: 'generic'; -} - -/** -* Array object data. -*/ -type ArrayObject = MaskArrayObject | Int32ArrayObject | BooleanArrayObject | IntegerArrayObject | null; - -/** -* Interface describing an array index object. -*/ -interface BaseArrayIndex { - /** - * Read-only property returning the data associated with an `ArrayIndex` instance. - */ - data: IndexArray; - - /** - * Read-only property returning the underlying array index data type. - */ - dtype: DataType; - - /** - * Read-only property returning the unique identifier associated with an `ArrayIndex` instance. - */ - id: string; - - /** - * Boolean indicating if an `ArrayIndex` instance is actively cached. - */ - isCached: boolean; - - /** - * Read-only property returning the array index type. - */ - type: 'int' | 'bool' | 'mask'; - - /** - * Serializes an `ArrayIndex` to a string. - * - * @returns serialized string - * - * @example - * var Uint8Array = require( './../../../uint8' ); - * - * var idx = new ArrayIndex( new Uint8Array( [ 1, 0, 1, 0 ] ) ); - * // returns - * - * var str = idx.toString(); - * // e.g., 'ArrayIndex<0>' - */ - toString(): string; -} - -/** -* Interface describing a mask array index object. -*/ -interface MaskArrayIndex extends BaseArrayIndex { - /** - * Read-only property returning the array index type. - */ - type: 'mask'; - - /** - * Read-only property returning the underlying array index data type. - */ - dtype: 'uint8'; - - /** - * Read-only property returning the underlying array data. - */ - data: Uint8Array; -} - -/** -* Interface describing an integer array index object. -*/ -interface Int32ArrayIndex extends BaseArrayIndex { - /** - * Read-only property returning the array index type. - */ - type: 'int'; - - /** - * Read-only property returning the underlying array index data type. - */ - dtype: 'int32'; - - /** - * Read-only property returning the underlying array data. - */ - data: Int32Array; -} - -/** -* Interface describing a boolean array index object. -*/ -interface BooleanArrayIndex extends BaseArrayIndex { - /** - * Read-only property returning the array index type. - */ - type: 'bool'; - - /** - * Read-only property returning the underlying array index data type. - */ - dtype: 'generic'; - - /** - * Read-only property returning the underlying array data. - */ - data: BooleanIndexArray; -} - -/** -* Interface describing an integer array index object. -*/ -interface IntegerArrayIndex extends BaseArrayIndex { - /** - * Read-only property returning the array index type. - */ - type: 'int'; - - /** - * Read-only property returning the underlying array index data type. - */ - dtype: 'generic'; - - /** - * Read-only property returning the underlying array data. - */ - data: IntegerIndexArray; -} - -/** -* Array index object. -*/ -type ArrayIndex = MaskArrayIndex | Int32ArrayIndex | BooleanArrayIndex | IntegerArrayIndex; - /** * Interface defining an `ArrayIndex` constructor which is both "newable" and "callable". */ @@ -372,6 +121,7 @@ interface Constructor { * // returns */ new( x: IndexArray, options?: Options ): ArrayIndex; + /** * Array index constructor. * @@ -512,7 +262,7 @@ interface Constructor { * var dt = o.dtype; * // returns 'uint8' */ - get( id: string ): T; + get( id: string ): T | null; } /** diff --git a/index/docs/types/test.ts b/index/docs/types/test.ts index d330d1fb..890409cb 100644 --- a/index/docs/types/test.ts +++ b/index/docs/types/test.ts @@ -132,7 +132,7 @@ import ArrayIndex = require( './index' ); // Attached to the main export is a `get` function which returns array object data... { - ArrayIndex.get( '0' ); // $ExpectType ArrayObject + ArrayIndex.get( '0' ); // $ExpectType IndexArrayObject | null } // The compiler throws an error if the `get` method is provided first argument which is not a string... diff --git a/to-fancy/README.md b/to-fancy/README.md index 96f17a1a..242a6455 100644 --- a/to-fancy/README.md +++ b/to-fancy/README.md @@ -208,6 +208,19 @@ var v = y[ 10 ]; The returned function supports the same options as above. When the returned function is provided option values, those values override the factory method defaults. +#### array2fancy.idx( x\[, options] ) + +Wraps a provided array as an array index object. + +```javascript +var x = [ 1, 2, 3, 4 ]; + +var idx = array2fancy.idx( x ); +// returns +``` + +For documentation and usage, see [`ArrayIndex`][@stdlib/array/index] + @@ -236,8 +249,6 @@ Accordingly, when `strict` is `false`, one may observe the following behaviors: ```javascript -var idx = require( '@stdlib/array/index' ); - var x = array2fancy( [ 1, 2, 3, 4 ], { 'strict': false }); @@ -258,7 +269,8 @@ v = x[ '10:' ]; // returns [] // Access one or more out-of-bounds indices: -v = x[ idx( [ 10, 20 ] ) ]; +var i = array2fancy.idx( [ 10, 20 ] ); +v = x[ i ]; // throws ``` @@ -267,8 +279,6 @@ When `strict` is `true`, fancy arrays normalize index behavior and consistently ```javascript -var idx = require( '@stdlib/array/index' ); - var x = array2fancy( [ 1, 2, 3, 4 ], { 'strict': true }); @@ -289,7 +299,8 @@ v = x[ '10:' ]; // throws // Access one or more out-of-bounds indices: -v = x[ idx( [ 10, 20 ] ) ]; +var i = array2fancy.idx( [ 10, 20 ] ); +v = x[ i ]; // throws ``` @@ -445,7 +456,6 @@ im = imag( v ); ```javascript var Uint8Array = require( '@stdlib/array/uint8' ); var Int32Array = require( '@stdlib/array/int32' ); -var idx = require( '@stdlib/array/index' ); var array2fancy = require( '@stdlib/array/to-fancy' ); var x = [ 1, 2, 3, 4, 5, 6 ]; @@ -472,6 +482,8 @@ z = y[ ':' ]; // returns [ 1, 2, -10, -9, -8, 6 ] // Array index retrieval: +var idx = array2fancy.idx; + var i = idx( [ 1, 3, 4 ] ); // integer index array z = y[ i ]; // returns [ 2, -9, -8 ] diff --git a/to-fancy/benchmark/benchmark.get.js b/to-fancy/benchmark/benchmark.get.js index 7db65631..14388ae8 100644 --- a/to-fancy/benchmark/benchmark.get.js +++ b/to-fancy/benchmark/benchmark.get.js @@ -138,3 +138,36 @@ bench( pkg+'::get,subsequence:len=1', opts, function benchmark( b ) { b.pass( 'benchmark finished' ); b.end(); }); + +bench( pkg+'::get,integer_array:len=1', opts, function benchmark( b ) { + var values; + var opts; + var x; + var v; + var i; + + x = array2fancy( zeroTo( 100, 'generic' ) ); + + opts = { + 'persist': true + }; + values = [ + array2fancy.idx( [ 1 ], opts ), + array2fancy.idx( [ 2 ], opts ), + array2fancy.idx( [ 3 ], opts ) + ]; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = x[ values[ i%values.length ] ]; + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isCollection( v ) ) { + b.fail( 'should return an array' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/to-fancy/docs/repl.txt b/to-fancy/docs/repl.txt index 09ea8916..f22e537f 100644 --- a/to-fancy/docs/repl.txt +++ b/to-fancy/docs/repl.txt @@ -132,6 +132,33 @@ > y[ '::-1' ] [ 4, 3, 2, 1 ] + +{{alias}}.idx( x[, options] ) + Wraps a provided array as an array index object. + + For documentation and usage, see `{{alias:@stdlib/array/index}}`. + + Parameters + ---------- + x: Array|TypedArray|Object + Input array. + + options: Object (optional) + Function options. + + options.persist: boolean (optional) + Boolean indicating whether to continue persisting an index object after + first usage. Default: false. + + Returns + ------- + out: ArrayIndex + ArrayIndex instance. + + Examples + -------- + > var idx = {{alias}}.idx( [ 1, 2, 3, 4 ] ); + See Also -------- diff --git a/to-fancy/docs/types/index.d.ts b/to-fancy/docs/types/index.d.ts index 2cd4da18..3fb91698 100644 --- a/to-fancy/docs/types/index.d.ts +++ b/to-fancy/docs/types/index.d.ts @@ -20,27 +20,8 @@ /// -import { Collection, ArrayLike, AccessorArrayLike, Complex128Array, Complex64Array, DataType } from '@stdlib/types/array'; - -/** -* Interface describing an index object. -*/ -interface IndexObject { - /** - * Underlying array index data. - */ - data: Collection | AccessorArrayLike; - - /** - * Index type. - */ - type: 'mask' | 'bool' | 'int'; - - /** - * Underlying array data type. - */ - dtype: DataType | null; -} +import { Collection, ArrayLike, AccessorArrayLike, Complex128Array, Complex64Array, ArrayIndexObject } from '@stdlib/types/array'; +import ArrayIndex = require( './../../../index' ); /** * Interface describing a cache for resolving array index objects. @@ -52,7 +33,7 @@ interface Cache { * @param id - identifier * @returns index data */ - get( id: any ): IndexObject | null; + get( id: any ): ArrayIndexObject | null; } /** @@ -415,6 +396,24 @@ interface Array2Fancy { * // returns [ 1, 2, 3, 4 ] */ factory( options?: Options ): Array2Fancy; + + /** + * Array index constructor. + * + * @param x - input array + * @param options - function options + * @param options.persist - boolean indicating whether to continue persisting an index object after first usage + * @returns ArrayIndex instance + * + * @example + * var Uint8Array = require( './../../../uint8' ); + * + * var x = new Uint8Array( [ 1, 0, 1, 0 ] ); + * + * var idx = array2fancy.idx( x ); + * // returns + */ + idx: typeof ArrayIndex; } /** diff --git a/to-fancy/docs/types/test.ts b/to-fancy/docs/types/test.ts index 658d18b0..3952b732 100644 --- a/to-fancy/docs/types/test.ts +++ b/to-fancy/docs/types/test.ts @@ -161,3 +161,23 @@ import array2fancy = require( './index' ); { array2fancy.factory( {}, {} ); // $ExpectError } + +// Attached to the function is an `idx` method which returns an array index... +{ + const x = [ 1, 2, 3, 4 ]; + const y = [ true, false, true, false ]; + const z = new Uint8Array( [ 1, 0, 1, 0 ] ); + const w = new Int32Array( [ 1, 2, 3, 4 ] ); + + array2fancy.idx( x ); // $ExpectType IntegerArrayIndex + array2fancy.idx( x, {} ); // $ExpectType IntegerArrayIndex + + array2fancy.idx( y ); // $ExpectType BooleanArrayIndex + array2fancy.idx( y, {} ); // $ExpectType BooleanArrayIndex + + array2fancy.idx( z ); // $ExpectType MaskArrayIndex + array2fancy.idx( z, {} ); // $ExpectType MaskArrayIndex + + array2fancy.idx( w ); // $ExpectType Int32ArrayIndex + array2fancy.idx( w, {} ); // $ExpectType Int32ArrayIndex +} diff --git a/to-fancy/examples/index.js b/to-fancy/examples/index.js index 405e2467..37d789a0 100644 --- a/to-fancy/examples/index.js +++ b/to-fancy/examples/index.js @@ -20,7 +20,6 @@ var Uint8Array = require( './../../uint8' ); var Int32Array = require( './../../int32' ); -var idx = require( './../../index' ); var array2fancy = require( './../lib' ); var x = [ 1, 2, 3, 4, 5, 6 ]; @@ -52,6 +51,8 @@ console.log( z ); // => [ 1, 2, -10, -9, -8, 6 ] // Array index retrieval: +var idx = array2fancy.idx; + var i = idx( [ 1, 3, 4 ] ); // integer index array z = y[ i ]; console.log( z ); diff --git a/to-fancy/lib/index.js b/to-fancy/lib/index.js index 72229b29..88895116 100644 --- a/to-fancy/lib/index.js +++ b/to-fancy/lib/index.js @@ -50,6 +50,7 @@ // MODULES // var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var ArrayIndex = require( './../../index' ); var main = require( './main.js' ); var factory = require( './factory.js' ); @@ -57,6 +58,7 @@ var factory = require( './factory.js' ); // MAIN // setReadOnly( main, 'factory', factory ); +setReadOnly( main, 'idx', ArrayIndex ); // EXPORTS // diff --git a/to-fancy/test/test.js b/to-fancy/test/test.js index be5024e7..c9cc57a8 100644 --- a/to-fancy/test/test.js +++ b/to-fancy/test/test.js @@ -22,6 +22,7 @@ var tape = require( 'tape' ); var hasOwnProp = require( '@stdlib/assert/has-own-property' ); +var ArrayIndex = require( './../../index' ); var array2fancy = require( './../lib' ); @@ -38,3 +39,9 @@ tape( 'attached to the main export is a `factory` method', function test( t ) { t.strictEqual( typeof array2fancy.factory, 'function', 'has method' ); t.end(); }); + +tape( 'attached to the main export is an `ArrayIndex` constructor', function test( t ) { + t.strictEqual( hasOwnProp( array2fancy, 'idx' ), true, 'has property' ); + t.strictEqual( array2fancy.idx, ArrayIndex, 'returns expected value' ); + t.end(); +});