Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit d26a1ee

Browse filesBrowse files
committed
Auto-generated commit
1 parent efabb6e commit d26a1ee
Copy full SHA for d26a1ee

File tree

9 files changed

+117
-33
lines changed
Filter options

9 files changed

+117
-33
lines changed

‎NOTICE

Copy file name to clipboard
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Copyright (c) 2016-2021 The Stdlib Authors.
1+
Copyright (c) 2016-2022 The Stdlib Authors.

‎README.md

Copy file name to clipboardExpand all lines: README.md
+12-10Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -91,11 +91,11 @@ arr = array( array( [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ] ) );
9191

9292
The function accepts the following `options`:
9393

94-
- `buffer`: data source. If provided along with a `buffer` argument, the argument takes precedence.
94+
- **buffer**: data source. If provided along with a `buffer` argument, the argument takes precedence.
9595

96-
- `dtype`: underlying storage [data type][@stdlib/ndarray/dtypes]. If not specified and a data source is provided, the data type is inferred from the provided data source. If an input data source is not of the same type, this option specifies the data type to which to cast the input data. For non-[`ndarray`][@stdlib/ndarray/ctor] generic array data sources, the function casts generic array data elements to the default data type. In order to prevent this cast, the `dtype` option **must** be explicitly set to `'generic'`. 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'`.
96+
- **dtype**: underlying storage [data type][@stdlib/ndarray/dtypes]. If not specified and a data source is provided, the data type is inferred from the provided data source. If an input data source is not of the same type, this option specifies the data type to which to cast the input data. For non-[`ndarray`][@stdlib/ndarray/ctor] generic array data sources, the function casts generic array data elements to the default data type. In order to prevent this cast, the `dtype` option **must** be explicitly set to `'generic'`. 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'`.
9797

98-
- `order`: specifies the memory layout of the data source as either row-major (C-style) or column-major (Fortran-style). The option may be one of the following values:
98+
- **order**: specifies the memory layout of the data source as either row-major (C-style) or column-major (Fortran-style). The option may be one of the following values:
9999

100100
- `row-major`: the order of the returned array is row-major.
101101
- `column-major`: the order of the returned array is column-major.
@@ -104,15 +104,15 @@ The function accepts the following `options`:
104104

105105
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'`.
106106

107-
- `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. For 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.
107+
- **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. For 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.
108108

109-
- `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`.
109+
- **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`.
110110

111-
- `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`.
111+
- **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`.
112112

113-
- `ndmin`: specifies the minimum number of dimensions. If an array shape has fewer dimensions than required by `ndmin`, the function **prepends** singleton dimensions to the array shape in order to satisfy the dimensions requirement. Default: `0`.
113+
- **ndmin**: specifies the minimum number of dimensions. If an array shape has fewer dimensions than required by `ndmin`, the function **prepends** singleton dimensions to the array shape in order to satisfy the dimensions requirement. Default: `0`.
114114

115-
- `casting`: specifies the casting rule used to determine acceptable casts. The option may be one of the following values:
115+
- **casting**: specifies the casting rule used to determine acceptable casts. The option may be one of the following values:
116116

117117
- `none`: only allow casting between identical types.
118118
- `equiv`: allow casting between identical and byte swapped types.
@@ -122,15 +122,17 @@ The function accepts the following `options`:
122122

123123
Default: `'safe'`.
124124

125-
- `mode`: specifies how to handle indices which exceed array dimensions.
125+
- **mode**: specifies how to handle indices which exceed array dimensions.
126126

127127
- `throw`: specifies that an [`ndarray`][@stdlib/ndarray/ctor] instance should throw an error when an index exceeds array dimensions.
128128
- `wrap`: specifies that an [`ndarray`][@stdlib/ndarray/ctor] instance should wrap around an index exceeding array dimensions using modulo arithmetic.
129129
- `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.
130130

131131
Default: `'throw'`.
132132

133-
- `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 ]`.
133+
- **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 ]`.
134+
135+
- **readonly**: `boolean` indicating whether an [`ndarray`][@stdlib/ndarray/ctor] instance should be **read-only**. Default: `false`.
134136

135137
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.
136138

‎docs/repl.txt

Copy file name to clipboardExpand all lines: docs/repl.txt
+3Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,9 @@
122122

123123
Default: [ options.mode ].
124124

125+
options.readonly: boolean (optional)
126+
Boolean indicating whether an array should be read-only. Default: false.
127+
125128
Returns
126129
-------
127130
out: ndarray

‎docs/types/index.d.ts

Copy file name to clipboardExpand all lines: docs/types/index.d.ts
+65-13Lines changed: 65 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,9 @@
1919
// TypeScript Version: 2.0
2020

2121
/// <reference types="@stdlib/types"/>
22-
/// <reference types="node"/>
2322

24-
import { Buffer } from 'buffer';
25-
import { ArrayLike, TypedArray } from '@stdlib/types/array';
26-
import { DataType, ndarray, Mode, Order } from '@stdlib/types/ndarray';
23+
import { ArrayLike } from '@stdlib/types/array';
24+
import { DataType, ndarray, Mode, Order, Shape } from '@stdlib/types/ndarray';
2725

2826
/**
2927
* Interface defining function options.
@@ -39,11 +37,6 @@ interface Options {
3937
*/
4038
order?: Order;
4139

42-
/**
43-
* Array shape.
44-
*/
45-
shape?: ArrayLike<number>;
46-
4740
/**
4841
* Specifies how to handle indices which exceed array dimensions (default: 'throw').
4942
*/
@@ -73,12 +66,69 @@ interface Options {
7366
* Casting rule used to determine what constitutes an acceptable cast (default: 'safe').
7467
*/
7568
casting?: string;
69+
70+
/**
71+
* Boolean indicating if an array should be read-only (default: false).
72+
*/
73+
readonly?: boolean;
74+
}
75+
76+
/**
77+
* Interface describing function options.
78+
*/
79+
interface OptionsWithShape extends Options {
80+
/**
81+
* Array shape.
82+
*/
83+
shape: Shape;
84+
85+
/**
86+
* Data source.
87+
*
88+
* ## Notes
89+
*
90+
* - If provided along with a `buffer` argument, the argument takes precedence.
91+
*/
92+
buffer?: ArrayLike<any>;
7693
}
7794

7895
/**
79-
* Array or typed array.
96+
* Interface describing function options.
8097
*/
81-
type ArrayOrBufferOrTypedArray = Array<any> | TypedArray | Buffer | null;
98+
interface OptionsWithBuffer extends Options {
99+
/**
100+
* Array shape.
101+
*/
102+
shape?: Shape;
103+
104+
/**
105+
* Data source.
106+
*
107+
* ## Notes
108+
*
109+
* - If provided along with a `buffer` argument, the argument takes precedence.
110+
*/
111+
buffer: ArrayLike<any>;
112+
}
113+
114+
/**
115+
* Interface describing function options.
116+
*/
117+
interface ExtendedOptions extends Options {
118+
/**
119+
* Array shape.
120+
*/
121+
shape?: Shape;
122+
123+
/**
124+
* Data source.
125+
*
126+
* ## Notes
127+
*
128+
* - If provided along with a `buffer` argument, the argument takes precedence.
129+
*/
130+
buffer?: ArrayLike<any>;
131+
}
82132

83133
/**
84134
* Returns a multidimensional array.
@@ -94,6 +144,7 @@ type ArrayOrBufferOrTypedArray = Array<any> | TypedArray | Buffer | null;
94144
* @param options.flatten - boolean indicating whether to automatically flatten generic array data sources (default: true)
95145
* @param options.ndmin - minimum number of dimensions (default: 0)
96146
* @param options.casting - casting rule used to determine what constitutes an acceptable cast (default: 'safe')
147+
* @param options.readonly - boolean indicating whether an array should be read-only
97148
* @throws must provide valid options
98149
* @throws must provide either an array shape, data source, or both
99150
* @throws invalid cast
@@ -113,7 +164,7 @@ type ArrayOrBufferOrTypedArray = Array<any> | TypedArray | Buffer | null;
113164
* var v = arr.get( 0 );
114165
* // returns [ 1, 2 ]
115166
*/
116-
declare function array( options: Options ): ndarray;
167+
declare function array( options: OptionsWithShape | OptionsWithBuffer ): ndarray; // tslint:disable-line:max-line-length
117168

118169
/**
119170
* Returns a multidimensional array.
@@ -130,6 +181,7 @@ declare function array( options: Options ): ndarray;
130181
* @param options.flatten - boolean indicating whether to automatically flatten generic array data sources (default: true)
131182
* @param options.ndmin - minimum number of dimensions (default: 0)
132183
* @param options.casting - casting rule used to determine what constitutes an acceptable cast (default: 'safe')
184+
* @param options.readonly - boolean indicating whether an array should be read-only
133185
* @throws must provide valid options
134186
* @throws must provide either an array shape, data source, or both
135187
* @throws invalid cast
@@ -168,7 +220,7 @@ declare function array( options: Options ): ndarray;
168220
* var v = arr.get( 0, 0 );
169221
* // returns 1.0
170222
*/
171-
declare function array( buffer: ArrayOrBufferOrTypedArray, options?: Options ): ndarray; // tslint-disable-line max-line-length
223+
declare function array( buffer: ArrayLike<any>, options?: ExtendedOptions ): ndarray; // tslint:disable-line:max-line-length
172224

173225

174226
// EXPORTS //

‎docs/types/test.ts

Copy file name to clipboardExpand all lines: docs/types/test.ts
+23-3Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,17 +23,19 @@ import array = require( './index' );
2323

2424
// The function returns an ndarray...
2525
{
26-
array( ( [ [ 1, 2 ], [ 3, 4 ] ] ) ); // $ExpectType ndarray
26+
array( [ [ 1, 2 ], [ 3, 4 ] ] ); // $ExpectType ndarray
2727
array( new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] ), { 'shape': [ 2, 2 ] } ); // $ExpectType ndarray
28+
array( { 'shape': [ 2, 2 ] } ); // $ExpectType ndarray
29+
array( { 'buffer': [ [ 1, 2 ], [ 3, 4 ] ] } ); // $ExpectType ndarray
2830
}
2931

3032
// The function does not compile if provided a first argument which is not an array, buffer, or options object...
3133
{
3234
array( true ); // $ExpectError
3335
array( false ); // $ExpectError
3436
array( undefined ); // $ExpectError
35-
array( '5' ); // $ExpectError
36-
array( ( x: number ): number => x ); // $ExpectError
37+
array( 5 ); // $ExpectError
38+
array( null ); // $ExpectError
3739
}
3840

3941
// The function does not compile if provided a second argument which is not an options object...
@@ -229,6 +231,24 @@ import array = require( './index' );
229231
array( { 'casting': ( x: number ): number => x } ); // $ExpectError
230232
}
231233

234+
// The compiler throws an error if the function is provided a `readonly` option which is not a boolean...
235+
{
236+
const buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] );
237+
array( buffer, { 'readonly': 'abc' } ); // $ExpectError
238+
array( buffer, { 'readonly': 123 } ); // $ExpectError
239+
array( buffer, { 'readonly': null } ); // $ExpectError
240+
array( buffer, { 'readonly': [] } ); // $ExpectError
241+
array( buffer, { 'readonly': {} } ); // $ExpectError
242+
array( buffer, { 'readonly': ( x: number ): number => x } ); // $ExpectError
243+
244+
array( { 'readonly': 'abc' } ); // $ExpectError
245+
array( { 'readonly': 123 } ); // $ExpectError
246+
array( { 'readonly': null } ); // $ExpectError
247+
array( { 'readonly': [] } ); // $ExpectError
248+
array( { 'readonly': {} } ); // $ExpectError
249+
array( { 'readonly': ( x: number ): number => x } ); // $ExpectError
250+
}
251+
232252
// The function does not compile if provided an invalid number of arguments...
233253
{
234254
const buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0 ] );

‎lib/cast_buffer.js

Copy file name to clipboardExpand all lines: lib/cast_buffer.js
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ function castBuffer( buffer, len, dtype ) {
5858
} else {
5959
out = new ctor( len );
6060
for ( i = 0; i < len; i++ ) {
61-
out[ i ] = buffer[ i ];
61+
out[ i ] = buffer[ i ]; // TODO: wrap and use accessors here and above
6262
}
6363
}
6464
return out;

‎lib/copy_view.js

Copy file name to clipboardExpand all lines: lib/copy_view.js
+4-4Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ function generic( arr ) {
4141
len = arr.length;
4242
out = [];
4343
for ( i = 0; i < len; i++ ) {
44-
out.push( arr.get( i ) );
44+
out.push( arr.get( i ) ); // FIXME: what if `arr` has more than one dimensions?
4545
}
4646
return out;
4747
}
@@ -61,7 +61,7 @@ function binary( arr ) {
6161
len = arr.length;
6262
out = allocUnsafe( len );
6363
for ( i = 0; i < len; i++ ) {
64-
out[ i ] = arr.get( i );
64+
out[ i ] = arr.get( i ); // FIXME: what if `arr` has more than one dimensions?
6565
}
6666
return out;
6767
}
@@ -82,9 +82,9 @@ function typed( arr, dtype ) {
8282

8383
ctor = bufferCtors( dtype );
8484
len = arr.length;
85-
out = new ctor( len );
85+
out = new ctor( len ); // FIXME: need to account for complex number arrays; in which case, we may want to do something similar to `array/convert`
8686
for ( i = 0; i < len; i++ ) {
87-
out[ i ] = arr.get( i );
87+
out[ i ] = arr.get( i ); // FIXME: what if `arr` has more than one dimensions?
8888
}
8989
return out;
9090
}

‎lib/defaults.json

Copy file name to clipboardExpand all lines: lib/defaults.json
+2-1Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,6 @@
55
"flatten": true,
66
"mode": "throw",
77
"ndmin": 0,
8-
"order": "row-major"
8+
"order": "row-major",
9+
"readonly": false
910
}

‎lib/main.js

Copy file name to clipboardExpand all lines: lib/main.js
+6Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ var expandStrides = require( './expand_strides.js' );
6464
* @param {boolean} [options.flatten=true] - boolean indicating whether to automatically flatten generic array data sources
6565
* @param {NonNegativeInteger} [options.ndmin=0] - minimum number of dimensions
6666
* @param {string} [options.casting="safe"] - casting rule used to determine what constitutes an acceptable cast
67+
* @param {boolean} [options.readonly=false] - boolean indicating if an array should be read-only
6768
* @throws {TypeError} options argument must be an object
6869
* @throws {TypeError} must provide valid options
6970
* @throws {Error} must provide either an array shape, data source, or both
@@ -245,6 +246,11 @@ function array() {
245246
} else {
246247
nopts.submode = [ nopts.mode ];
247248
}
249+
if ( hasOwnProp( options, 'readonly' ) ) {
250+
nopts.readonly = options.readonly;
251+
} else {
252+
nopts.readonly = defaults.readonly;
253+
}
248254
if ( hasOwnProp( options, 'copy' ) ) {
249255
opts.copy = options.copy;
250256
if ( !isBoolean( opts.copy ) ) {

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.