Skip to content

Commit 079b805

Browse files
PlaneshifterPlaneshifter
committed
Add Typescript definition
1 parent 850f97d commit 079b805

3 files changed

Lines changed: 394 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/ind2sub/docs/types/index.d.ts‎

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
// TypeScript Version: 2.0
20+
21+
/// <reference types="@stdlib/types"/>
22+
/// <reference types="node"/>
23+
24+
import { ArrayLike } from '@stdlib/types/array';
25+
import { Mode, Order } from '@stdlib/types/ndarray';
26+
27+
/**
28+
* Interface defining function options.
29+
*/
30+
interface Options {
31+
/**
32+
* Specifies how to handle a linear index which exceeds array dimensions (default: 'throw').
33+
*/
34+
mode?: Mode;
35+
36+
/**
37+
* specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major').
38+
*/
39+
order?: Order;
40+
}
41+
42+
interface Ind2Sub {
43+
/**
44+
* Converts a linear index to an array of subscripts.
45+
*
46+
* ## Notes
47+
*
48+
* - The function accepts the following "modes":
49+
*
50+
* - `throw`: throws an error when a linear index exceeds array dimensions.
51+
* - `wrap`: wrap around a linear index exceeding array dimensions using modulo arithmetic.
52+
* - `clamp`: set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
53+
*
54+
*
55+
* @param shape - array shape
56+
* @param idx - linear index
57+
* @param options - function options
58+
* @param options.mode - specifies how to handle a linear index which exceeds array dimensions (default: 'throw')
59+
* @param options.order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major')
60+
* @throws shape argument must be an array-like object containing nonnegative integers
61+
* @throws must provide valid options
62+
* @throws must provide a linear index which does not exceed array dimensions
63+
* @returns subscripts
64+
*
65+
* @example
66+
* var s = ind2sub( [ 3, 3, 3 ], 17 );
67+
* // returns [ 1, 2, 2 ]
68+
*/
69+
( shape: ArrayLike<number>, idx: number, options?: Options ): Array<number>;
70+
71+
/**
72+
* Converts a linear index to an array of subscripts and assigns results to a provided output array.
73+
*
74+
* ## Notes
75+
*
76+
* - The function accepts the following "modes":
77+
*
78+
* - `throw`: throws an error when a linear index exceeds array dimensions.
79+
* - `wrap`: wrap around a linear index exceeding array dimensions using modulo arithmetic.
80+
* - `clamp`: set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
81+
*
82+
*
83+
* @param shape - array shape
84+
* @param idx - linear index
85+
* @param options - function options
86+
* @param options.mode - specifies how to handle a linear index which exceeds array dimensions (default: 'throw')
87+
* @param options.order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major')
88+
* @param out - output array
89+
* @throws output argument must be either an array, typed array, or an object
90+
* @throws shape argument must be an array-like object containing nonnegative integers
91+
* @throws must provide valid options
92+
* @throws must provide a linear index which does not exceed array dimensions
93+
* @returns subscripts
94+
*
95+
* @example
96+
* var shape = [ 3, 3, 3 ];
97+
* var out = [ 0, 0, 0 ];
98+
*
99+
* var s = ind2sub.assign( shape, 17, out );
100+
* // returns [ 1, 2, 2 ]
101+
*
102+
* var bool = ( s === out );
103+
* // returns true
104+
*/
105+
assign( shape: ArrayLike<number>, idx: number, options: Options, out: any ): Array<number>; // tslint-disable-line max-line-length
106+
107+
/**
108+
* Converts a linear index to an array of subscripts and assigns results to a provided output array.
109+
*
110+
* ## Notes
111+
*
112+
* - The function accepts the following "modes":
113+
*
114+
* - `throw`: throws an error when a linear index exceeds array dimensions.
115+
* - `wrap`: wrap around a linear index exceeding array dimensions using modulo arithmetic.
116+
* - `clamp`: set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
117+
*
118+
*
119+
* @param shape - array shape
120+
* @param idx - linear index
121+
* @param out - output array
122+
* @throws output argument must be either an array, typed array, or an object
123+
* @throws shape argument must be an array-like object containing nonnegative integers
124+
* @throws must provide a linear index which does not exceed array dimensions
125+
* @returns subscripts
126+
*
127+
* @example
128+
* var shape = [ 3, 3, 3 ];
129+
* var out = [ 0, 0, 0 ];
130+
*
131+
* var s = ind2sub.assign( shape, 17, out );
132+
* // returns [ 1, 2, 2 ]
133+
*
134+
* var bool = ( s === out );
135+
* // returns true
136+
*/
137+
assign( shape: ArrayLike<number>, idx: number, out: any ): Array<number>;
138+
}
139+
140+
/**
141+
* Converts a linear index to an array of subscripts.
142+
*
143+
* ## Notes
144+
*
145+
* - The function accepts the following "modes":
146+
*
147+
* - `throw`: throws an error when a linear index exceeds array dimensions.
148+
* - `wrap`: wrap around a linear index exceeding array dimensions using modulo arithmetic.
149+
* - `clamp`: set a linear index exceeding array dimensions to either `0` (minimum linear index) or the maximum linear index.
150+
*
151+
*
152+
* @param shape - array shape
153+
* @param idx - linear index
154+
* @param options - function options
155+
* @param options.mode - specifies how to handle a linear index which exceeds array dimensions (default: 'throw')
156+
* @param options.order - specifies whether an array is row-major (C-style) or column-major (Fortran-style) (default: 'row-major')
157+
* @throws shape argument must be an array-like object containing nonnegative integers
158+
* @throws must provide valid options
159+
* @throws must provide a linear index which does not exceed array dimensions
160+
* @returns subscripts
161+
*
162+
* @example
163+
* var s = ind2sub( [ 3, 3, 3 ], 17 );
164+
* // returns [ 1, 2, 2 ]
165+
*
166+
* @example
167+
* var shape = [ 3, 3, 3 ];
168+
* var out = [ 0, 0, 0 ];
169+
*
170+
* var s = ind2sub.assign( shape, 17, out );
171+
* // returns [ 1, 2, 2 ]
172+
*
173+
* var bool = ( s === out );
174+
* // returns true
175+
*/
176+
declare var ind2sub: Ind2Sub;
177+
178+
// EXPORTS //
179+
180+
export = ind2sub;

‎lib/node_modules/@stdlib/ndarray/ind2sub/docs/types/test.ts‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
/*
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2021 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
import ind2sub = require( './index' );
20+
21+
22+
// TESTS //
23+
24+
// The function returns an array of numbers...
25+
{
26+
const shape = [ 3, 3, 3 ];
27+
const idx = 17;
28+
ind2sub( shape, idx, { 'mode': 'throw' } ); // $ExpectType number[]
29+
ind2sub( shape, idx, { 'order': 'row-major' } ); // $ExpectType number[]
30+
}
31+
32+
// The function does not compile if provided a first argument which is not an array-like object containing numbers...
33+
{
34+
const idx = 17;
35+
ind2sub( true, idx ); // $ExpectError
36+
ind2sub( false, idx ); // $ExpectError
37+
ind2sub( null, idx ); // $ExpectError
38+
ind2sub( undefined, idx ); // $ExpectError
39+
ind2sub( '5', idx ); // $ExpectError
40+
ind2sub( [ '1', '2' ], idx ); // $ExpectError
41+
ind2sub( {}, idx ); // $ExpectError
42+
ind2sub( ( x: number ): number => x, idx ); // $ExpectError
43+
}
44+
45+
// The function does not compile if provided a second argument which is not a number...
46+
{
47+
const shape = [ 3, 3, 3 ];
48+
ind2sub( shape, 'abc' ); // $ExpectError
49+
ind2sub( shape, true ); // $ExpectError
50+
ind2sub( shape, false ); // $ExpectError
51+
ind2sub( shape, null ); // $ExpectError
52+
ind2sub( shape, undefined ); // $ExpectError
53+
ind2sub( shape, [] ); // $ExpectError
54+
ind2sub( shape, {} ); // $ExpectError
55+
ind2sub( shape, ( x: number ): number => x ); // $ExpectError
56+
}
57+
58+
// The function does not compile if provided a third argument which is not an options object...
59+
{
60+
const shape = [ 3, 3, 3 ];
61+
const idx = 17;
62+
ind2sub( shape, idx, 'abc' ); // $ExpectError
63+
ind2sub( shape, idx, 123 ); // $ExpectError
64+
ind2sub( shape, idx, true ); // $ExpectError
65+
ind2sub( shape, idx, false ); // $ExpectError
66+
ind2sub( shape, idx, null ); // $ExpectError
67+
ind2sub( shape, idx, [] ); // $ExpectError
68+
ind2sub( shape, idx, ( x: number ): number => x ); // $ExpectError
69+
}
70+
71+
// The compiler throws an error if the function is provided an `order` option which is not a recognized order...
72+
{
73+
const shape = [ 3, 3, 3 ];
74+
const idx = 17;
75+
ind2sub( shape, idx, { 'order': 'abc' } ); // $ExpectError
76+
ind2sub( shape, idx, { 'order': 123 } ); // $ExpectError
77+
ind2sub( shape, idx, { 'order': true } ); // $ExpectError
78+
ind2sub( shape, idx, { 'order': false } ); // $ExpectError
79+
ind2sub( shape, idx, { 'order': null } ); // $ExpectError
80+
ind2sub( shape, idx, { 'order': [] } ); // $ExpectError
81+
ind2sub( shape, idx, { 'order': {} } ); // $ExpectError
82+
ind2sub( shape, idx, { 'order': ( x: number ): number => x } ); // $ExpectError
83+
}
84+
85+
// The compiler throws an error if the function is provided a `mode` option which is not a recognized mode...
86+
{
87+
const shape = [ 3, 3, 3 ];
88+
const idx = 17;
89+
ind2sub( shape, idx, { 'mode': 'abc' } ); // $ExpectError
90+
ind2sub( shape, idx, { 'mode': 123 } ); // $ExpectError
91+
ind2sub( shape, idx, { 'mode': true } ); // $ExpectError
92+
ind2sub( shape, idx, { 'mode': false } ); // $ExpectError
93+
ind2sub( shape, idx, { 'mode': null } ); // $ExpectError
94+
ind2sub( shape, idx, { 'mode': [] } ); // $ExpectError
95+
ind2sub( shape, idx, { 'mode': {} } ); // $ExpectError
96+
ind2sub( shape, idx, { 'mode': ( x: number ): number => x } ); // $ExpectError
97+
}
98+
99+
// The function does not compile if provided an invalid number of arguments...
100+
{
101+
const shape = [ 3, 3, 3 ];
102+
const idx = 17;
103+
ind2sub(); // $ExpectError
104+
ind2sub( shape ); // $ExpectError
105+
ind2sub( shape, idx, {}, {} ); // $ExpectError
106+
}
107+
108+
// Attached to main export is a `assign` method which returns an array of numbers...
109+
{
110+
const shape = [ 3, 3, 3 ];
111+
const out = [ 0, 0, 0 ];
112+
ind2sub.assign( shape, 0, out ); // $ExpectType number[]
113+
ind2sub.assign( shape, 0, { 'mode': 'throw' }, out ); // $ExpectType number[]
114+
}
115+
116+
// The `assign` method does not compile if provided a first argument which is not an array-like object containing numbers...
117+
{
118+
const idx = 17;
119+
const out = [ 0, 0, 0 ];
120+
ind2sub.assign( 123, idx, out ); // $ExpectError
121+
ind2sub.assign( true, idx, out ); // $ExpectError
122+
ind2sub.assign( false, idx, out ); // $ExpectError
123+
ind2sub.assign( null, idx, out ); // $ExpectError
124+
ind2sub.assign( undefined, idx, out ); // $ExpectError
125+
ind2sub.assign( '5', idx, out ); // $ExpectError
126+
ind2sub.assign( [ '1', '2' ], idx, out ); // $ExpectError
127+
ind2sub.assign( {}, idx, out ); // $ExpectError
128+
ind2sub.assign( ( x: number ): number => x, idx, out ); // $ExpectError
129+
130+
const opts = {
131+
'order': 'row-major'
132+
};
133+
ind2sub.assign( 123, idx, opts, out ); // $ExpectError
134+
ind2sub.assign( true, idx, opts, out ); // $ExpectError
135+
ind2sub.assign( false, idx, opts, out ); // $ExpectError
136+
ind2sub.assign( null, idx, opts, out ); // $ExpectError
137+
ind2sub.assign( undefined, idx, opts, out ); // $ExpectError
138+
ind2sub.assign( '5', idx, opts, out ); // $ExpectError
139+
ind2sub.assign( [ '1', '2' ], idx, opts, out ); // $ExpectError
140+
ind2sub.assign( {}, idx, opts, out ); // $ExpectError
141+
ind2sub.assign( ( x: number ): number => x, idx, opts, out ); // $ExpectError
142+
}
143+
144+
// The `assign` method does not compile if provided a second argument which is not a number...
145+
{
146+
const shape = [ 3, 3, 3 ];
147+
const out = [ 0, 0, 0 ];
148+
ind2sub.assign( shape, true, out ); // $ExpectError
149+
ind2sub.assign( shape, false, out ); // $ExpectError
150+
ind2sub.assign( shape, null, out ); // $ExpectError
151+
ind2sub.assign( shape, undefined, out ); // $ExpectError
152+
ind2sub.assign( shape, 'abc', out ); // $ExpectError
153+
ind2sub.assign( shape, [ '1', '2' ], out ); // $ExpectError
154+
ind2sub.assign( shape, {}, out ); // $ExpectError
155+
ind2sub.assign( shape, ( x: number ): number => x, out ); // $ExpectError
156+
157+
const opts = {
158+
'order': 'row-major'
159+
};
160+
ind2sub.assign( shape, true opts, out ); // $ExpectError
161+
ind2sub.assign( shape, false opts, out ); // $ExpectError
162+
ind2sub.assign( shape, null opts, out ); // $ExpectError
163+
ind2sub.assign( shape, undefined opts, out ); // $ExpectError
164+
ind2sub.assign( shape, 'abc' opts, out ); // $ExpectError
165+
ind2sub.assign( shape, [ '1', '2' ] opts, out ); // $ExpectError
166+
ind2sub.assign( shape, {} opts, out ); // $ExpectError
167+
ind2sub.assign( shape, ( x: number ): number => x opts, out ); // $ExpectError
168+
}
169+
170+
// The `assign` method does not compile if provided an options argument which is not an options object...
171+
{
172+
const shape = [ 3, 3, 3 ];
173+
const idx = 17;
174+
const out = [ 0, 0, 0 ];
175+
ind2sub.assign( shape, idx, 'abc', out ); // $ExpectError
176+
ind2sub.assign( shape, idx, 123, out ); // $ExpectError
177+
ind2sub.assign( shape, idx, true, out ); // $ExpectError
178+
ind2sub.assign( shape, idx, false, out ); // $ExpectError
179+
ind2sub.assign( shape, idx, null, out ); // $ExpectError
180+
ind2sub.assign( shape, idx, undefined, out ); // $ExpectError
181+
ind2sub.assign( shape, idx, [], out ); // $ExpectError
182+
ind2sub.assign( shape, idx, ( x: number ): number => x, out ); // $ExpectError
183+
}
184+
185+
// The compiler throws an error if the `assign` method is provided an `order` option which is not a recognized order...
186+
{
187+
const shape = [ 3, 3, 3 ];
188+
const idx = 17;
189+
const out = [ 0, 0, 0 ];
190+
ind2sub.assign( shape, idx, { 'order': 'abc' }, out ); // $ExpectError
191+
ind2sub.assign( shape, idx, { 'order': 123 }, out ); // $ExpectError
192+
ind2sub.assign( shape, idx, { 'order': true }, out ); // $ExpectError
193+
ind2sub.assign( shape, idx, { 'order': false }, out ); // $ExpectError
194+
ind2sub.assign( shape, idx, { 'order': null }, out ); // $ExpectError
195+
ind2sub.assign( shape, idx, { 'order': [] }, out ); // $ExpectError
196+
ind2sub.assign( shape, idx, { 'order': {} }, out ); // $ExpectError
197+
ind2sub.assign( shape, idx, { 'order': ( x: number ): number => x }, out ); // $ExpectError
198+
}
199+
200+
// The compiler throws an error if the `assign` method is provided a `mode` option which is not a recognized mode...
201+
{
202+
const shape = [ 3, 3, 3 ];
203+
const idx = 17;
204+
const out = [ 0, 0, 0 ];
205+
ind2sub.assign( shape, idx, { 'mode': 'abc' }, out ); // $ExpectError
206+
ind2sub.assign( shape, idx, { 'mode': 123 }, out ); // $ExpectError
207+
ind2sub.assign( shape, idx, { 'mode': true }, out ); // $ExpectError
208+
ind2sub.assign( shape, idx, { 'mode': false }, out ); // $ExpectError
209+
ind2sub.assign( shape, idx, { 'mode': null }, out ); // $ExpectError
210+
ind2sub.assign( shape, idx, { 'mode': [] }, out ); // $ExpectError
211+
ind2sub.assign( shape, idx, { 'mode': {} }, out ); // $ExpectError
212+
ind2sub.assign( shape, idx, { 'mode': ( x: number ): number => x }, out ); // $ExpectError
213+
}

0 commit comments

Comments
 (0)