Skip to content

Commit 1e9c313

Browse files
kgrytekgryte
committed
Move implementation and add README
1 parent cfecf7c commit 1e9c313

13 files changed

Lines changed: 320 additions & 4 deletions

File tree

‎lib/node_modules/@stdlib/ndarray/array/README.md‎

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2018 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# Multidimensional Arrays
22+
23+
> Create a multidimensional array.
24+
25+
<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
26+
27+
<section class="intro">
28+
29+
</section>
30+
31+
<!-- /.intro -->
32+
33+
<!-- Package usage documentation. -->
34+
35+
<section class="usage">
36+
37+
## Usage
38+
39+
```javascript
40+
var array = require( '@stdlib/ndarray/array' );
41+
```
42+
43+
<a name="main"></a>
44+
45+
#### array( \[buffer,] \[options] )
46+
47+
Returns a multidimensional array.
48+
49+
```javascript
50+
// Create a 2x2 matrix:
51+
var arr = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ] );
52+
// returns <ndarray>
53+
```
54+
55+
To initialize multidimensional array data, provide a `buffer` argument, which may be a [generic array][@stdlib/array/generic], [typed array][@stdlib/array/typed], [Buffer][@stdlib/buffer/ctor], or [ndarray][@stdlib/ndarray/ctor].
56+
57+
<!-- eslint-disable object-curly-spacing, object-curly-newline -->
58+
59+
```javascript
60+
var Float64Array = require( '@stdlib/array/float64' );
61+
var alloc = require( '@stdlib/buffer/alloc' );
62+
63+
// Create an ndarray from a generic array linear data buffer:
64+
var arr = array( [ 1.0, 2.0, 3.0, 4.0 ], { 'shape': [ 2, 2 ] } );
65+
// returns <ndarray>
66+
67+
// Create an ndarray from a typed array linear data buffer:
68+
arr = array( new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] ), { 'shape': [ 2, 2 ] } );
69+
// returns <ndarray>
70+
71+
// Create an ndarray as a view over a Buffer:
72+
arr = array( alloc( 4 ), { 'shape': [ 2, 2 ] } );
73+
// returns <ndarray>
74+
75+
// Create an ndarray from another ndarray:
76+
arr = array( array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ] ) );
77+
// returns <ndarray>
78+
```
79+
80+
The function accepts the following `options`:
81+
82+
- `buffer`: data source. If provided along with a `buffer` argument, the argument takes precedence.
83+
- `dtype`: underlying storage [data type][@stdlib/ndarray/dtypes]. If the input data source is not of the same type, this option specifies the data type to which to cast the input data. Any time a cast is required, the `copy` option is set to `true`, as memory must be copied from the data source to an output data buffer. Default: `'float64'`.
84+
- `order`: specifies the memory layout of the data source as either row-major (C-style) or column-major (Fortran-style). If set to `'any'`, if a data source is column-major and not row-major, the order of the returned array is column-major; otherwise, the order of the returned array is always row-major. If set to `'same'`, the order of the returned array matches the order of an input data source. If set to either `'row-major'` or `'column-major'`, the order of the returned array is set to the option value. Note that specifying an order which differs from the order of a provided data source does **not** entail a conversion from one memory layout to another. In short, this option is descriptive, not prescriptive. Default: `'row-major'`.
85+
- `shape`: array shape (dimensions). If a shape is not specified, the function attempts to infer a shape based on a provided data source. For example, if provided a nested array, the function resolves nested array dimensions. If provided a multidimensional array data source, the function uses the array's associated shape. For most use cases, such inference suffices. In the remaining use cases, specifying a shape is necessary. For example, provide a shape to create a multidimensional array view over a linear data buffer, ignoring any existing shape meta data associated with a provided data source.
86+
- `flatten`: `boolean` indicating whether to automatically flatten generic array data sources. If an array shape is not specified, the shape is inferred from the dimensions of nested arrays prior to flattening. If a use case requires partial flattening, partially flatten prior to invoking this function and set the option value to `false` to prevent further flattening during invocation. Default: `true`.
87+
- `copy`: `boolean` indicating whether to (shallow) copy source data to a new data buffer. The function does **not** perform a deep copy. To prevent undesired shared changes in state for generic arrays containing objects, perform a deep copy **prior** to invoking this function. Default: `false`.
88+
- `codegen`: `boolean` indicating whether to use code generation. Default: `true`.
89+
- `mode`: specifies how to handle indices which exceed array dimensions. Default: `'throw'`.
90+
- `submode`: a mode array which specifies for each dimension how to handle subscripts which exceed array dimensions. If provided fewer modes than dimensions, the function recycles modes using modulo arithmetic. Default: `[ options.mode ]`.
91+
92+
The function supports the following `modes`:
93+
94+
- `throw`: specifies that an [`ndarray`][@stdlib/ndarray/ctor] instance should throw an error when an index exceeds array dimensions.
95+
- `wrap`: specifies that an [`ndarray`][@stdlib/ndarray/ctor] instance should wrap around an index exceeding array dimensions using modulo arithmetic.
96+
- `clamp`: specifies that an [`ndarray`][@stdlib/ndarray/ctor] instance should set an index exceeding array dimensions to either `0` (minimum index) or the maximum index.
97+
98+
By default, the function returns [`ndarray`][@stdlib/ndarray/ctor] instances which use code generation for fast element lookup. To disable code generation, set the `codegen` option to `false`.
99+
100+
```javascript
101+
var opts = {
102+
'codegen': false
103+
};
104+
105+
var arr = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], opts );
106+
// returns <ndarray>
107+
```
108+
109+
By default, an [`ndarray`][@stdlib/ndarray/ctor] instance **throws** when provided an index which exceeds array dimensions. To support alternative indexing behavior, set the `mode` option, which will affect all public methods for getting and setting array elements.
110+
111+
```javascript
112+
var opts = {
113+
'mode': 'clamp'
114+
};
115+
116+
var arr = array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ], opts );
117+
// returns <ndarray>
118+
119+
// Attempt to access an out-of-bounds linear index (clamped):
120+
var v = arr.iget( 10 );
121+
// returns 4.0
122+
```
123+
124+
By default, the `mode` option is applied to subscripts which exceed array dimensions. To specify behavior for each dimension, set the `submode` option.
125+
126+
```javascript
127+
var opts = {
128+
'submode': [ 'wrap', 'clamp' ]
129+
};
130+
131+
var arr = array( [ [[1.0, 2.0], [3.0, 4.0]], [[5.0, 6.0], [7.0, 8.0]] ], opts );
132+
// returns <ndarray>
133+
134+
// Attempt to access out-of-bounds subscripts:
135+
var v = arr.get( -2, 10, -1 ); // linear index: 3
136+
// returns 4.0
137+
```
138+
139+
By default, the function automatically flattens [generic array][@stdlib/array/generic] data sources. To prevent flattening, set the `flatten` option to `false`.
140+
141+
```javascript
142+
var opts = {
143+
'flatten': false
144+
};
145+
146+
// Create a generic array which will serve as our ndarray data source:
147+
var buf = [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ];
148+
149+
// Create a 2-element vector:
150+
var arr = array( buf, opts );
151+
// returns <ndarray>
152+
153+
// Retrieve the first vector element:
154+
var v = arr.get( 0 );
155+
// returns [ 1.0, 2.0 ]
156+
157+
var bool = ( v === buf[ 0 ] );
158+
// returns true
159+
```
160+
161+
</section>
162+
163+
<!-- /.usage -->
164+
165+
<!-- Package usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
166+
167+
<section class="notes">
168+
169+
* * *
170+
171+
## Notes
172+
173+
- Code generation can boost performance, but may be problematic in browser contexts enforcing a strict [content security policy][mdn-csp] (CSP). If running in or targeting an environment with a CSP, set the `codegen` option to `false`.
174+
- The implementation uses a variety of techniques to boost multidimensional creation performance; however, especially for highly specialized high-dimensional [`ndarray`][@stdlib/ndarray/ctor] instances, better performance may be realized by using [lower-level][@stdlib/ndarray/ctor] [constructors][@stdlib/ndarray/memoized-ctor].
175+
- The number of elements in a data source `buffer` **must** agree with a specified array `shape` (i.e., the function assumes a single-segment contiguous [`ndarray`][@stdlib/ndarray/ctor]). To create arbitrary multidimensional views over linear data buffers, use a [lower-level][@stdlib/ndarray/ctor] [constructor][@stdlib/ndarray/memoized-ctor].
176+
177+
</section>
178+
179+
<!-- /.notes -->
180+
181+
<!-- Package usage examples. -->
182+
183+
<section class="examples">
184+
185+
* * *
186+
187+
## Examples
188+
189+
<!-- eslint-disable stdlib/return-annotations-quote-props -->
190+
191+
<!-- eslint no-undef: "error" -->
192+
193+
```javascript
194+
var array = require( '@stdlib/ndarray/array' );
195+
196+
// Create a 4-dimensional array containing single-precision floating-point numbers:
197+
var arr = array({
198+
'dtype': 'float32',
199+
'shape': [ 3, 3, 3, 3 ]
200+
});
201+
202+
// Retrieve an array value:
203+
var v = arr.get( 1, 2, 1, 2 );
204+
// returns 0.0
205+
206+
// Set an array value:
207+
arr.set( 1, 2, 1, 2, 10.0 );
208+
209+
// Retrieve the array value:
210+
v = arr.get( 1, 2, 1, 2 );
211+
// returns 10.0
212+
213+
// Serialize the array as a string:
214+
var str = arr.toString();
215+
// returns ndarray( new Float32Array( [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 ] ), [ 3, 3, 3, 3 ], [ 27, 9, 3, 1 ], 0, 'row-major' )
216+
217+
// Serialize the array as JSON:
218+
str = JSON.stringify( arr.toJSON() );
219+
// returns {"type":"ndarray","dtype":"float32","flags":{},"order":"row-major","shape":[3,3,3,3],"strides":[27,9,3,1],"data":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,10,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]}
220+
```
221+
222+
</section>
223+
224+
<!-- /.examples -->
225+
226+
<!-- Section to include cited references. If references are included, add a horizontal rule *before* the section. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
227+
228+
<section class="references">
229+
230+
</section>
231+
232+
<!-- /.references -->
233+
234+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
235+
236+
<section class="links">
237+
238+
[mdn-csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
239+
240+
[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/stdlib
241+
242+
[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/stdlib
243+
244+
[@stdlib/ndarray/memoized-ctor]: https://github.com/stdlib-js/stdlib
245+
246+
[@stdlib/array/generic]: https://github.com/stdlib-js/stdlib
247+
248+
[@stdlib/array/typed]: https://github.com/stdlib-js/stdlib
249+
250+
[@stdlib/buffer/ctor]: https://github.com/stdlib-js/stdlib
251+
252+
</section>
253+
254+
<!-- /.links -->

lib/node_modules/@stdlib/ndarray/benchmark/benchmark.js renamed to lib/node_modules/@stdlib/ndarray/array/benchmark/benchmark.js

File renamed without changes.

lib/node_modules/@stdlib/ndarray/benchmark/python/numpy/benchmark.py renamed to lib/node_modules/@stdlib/ndarray/array/benchmark/python/numpy/benchmark.py

File renamed without changes.

lib/node_modules/@stdlib/ndarray/docs/repl.txt renamed to lib/node_modules/@stdlib/ndarray/array/docs/repl.txt

File renamed without changes.

lib/node_modules/@stdlib/ndarray/examples/index.js renamed to lib/node_modules/@stdlib/ndarray/array/examples/index.js

File renamed without changes.

lib/node_modules/@stdlib/ndarray/lib/cast_buffer.js renamed to lib/node_modules/@stdlib/ndarray/array/lib/cast_buffer.js

File renamed without changes.

lib/node_modules/@stdlib/ndarray/lib/copy_view.js renamed to lib/node_modules/@stdlib/ndarray/array/lib/copy_view.js

File renamed without changes.

lib/node_modules/@stdlib/ndarray/lib/defaults.json renamed to lib/node_modules/@stdlib/ndarray/array/lib/defaults.json

File renamed without changes.

lib/node_modules/@stdlib/ndarray/lib/index.js renamed to lib/node_modules/@stdlib/ndarray/array/lib/index.js

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@
2121
/**
2222
* Multidimensional array.
2323
*
24-
* @module @stdlib/ndarray
24+
* @module @stdlib/ndarray/array
2525
*
2626
* @example
27-
* var array = require( '@stdlib/ndarray' );
27+
* var array = require( '@stdlib/ndarray/array' );
2828
*
2929
* var arr = array( [ [ 1, 2 ], [ 3, 4 ] ] );
3030
* // returns <ndarray>
@@ -33,7 +33,7 @@
3333
* // returns 1
3434
*
3535
* @example
36-
* var array = require( '@stdlib/ndarray' );
36+
* var array = require( '@stdlib/ndarray/array' );
3737
*
3838
* var opts = {
3939
* 'dtype': 'generic',
@@ -48,7 +48,7 @@
4848
*
4949
* @example
5050
* var Float64Array = require( '@stdlib/array/float64' );
51-
* var array = require( '@stdlib/ndarray' );
51+
* var array = require( '@stdlib/ndarray/array' );
5252
*
5353
* var opts = {
5454
* 'shape': [ 2, 2 ]

lib/node_modules/@stdlib/ndarray/lib/is_array_like_object.js renamed to lib/node_modules/@stdlib/ndarray/array/lib/is_array_like_object.js

File renamed without changes.

0 commit comments

Comments
 (0)