You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
refactor!: remove support for non-ndarray arguments
This commit aligns the API with reductions (e.g., `stats/max`)
where top-level APIs only accept ndarrays.
BREAKING CHANGE: remove support for non-ndarray arguments
To migrate, users should wrap non-ndarray arguments using
`@stdlib/ndarray/array` or `@stdlib/ndarray/from-scalar` which will
convert non-ndarray arguments to ndarrays. In general, if a user
is providing a number, a user is likely to want a number in return.
Similarly for built-in array types. So always returning an ndarray
is likely not what a user wants. This change essentially requires
users to be explicit about what implementation and behavior they
desire. If a user still wants to retain previous behavior, they
can write a thin wrapper a top the new API which performs delegation
based on whether an input argument is a scalar, array, or an ndarray.
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: passed
- task: lint_package_json
status: passed
- task: lint_repl_help
status: passed
- task: lint_javascript_src
status: passed
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: passed
- task: lint_javascript_tests
status: passed
- task: lint_javascript_benchmarks
status: passed
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: passed
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: passed
- task: lint_license_headers
status: passed
---
Copy file name to clipboardExpand all lines: lib/node_modules/@stdlib/math/special/abs/README.md
+87-86Lines changed: 87 additions & 86 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,27 +20,12 @@ limitations under the License.
20
20
21
21
# abs
22
22
23
-
> Compute the [absolute value][absolute-value].
23
+
> Compute the [absolute value][@stdlib/math/base/special/abs] for each element in an [ndarray][@stdlib/ndarray/ctor].
24
24
25
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
26
27
27
<sectionclass="intro">
28
28
29
-
The [absolute value][absolute-value] is defined as
30
-
31
-
<!-- <equation class="equation" label="eq:absolute_value" align="center" raw="|x| = \begin{cases} x & \textrm{if}\ x \geq 0 \\ -x & \textrm{if}\ x < 0\end{cases}" alt="Absolute value"> -->
32
-
33
-
```math
34
-
|x| = \begin{cases} x & \textrm{if}\ x \geq 0 \\ -x & \textrm{if}\ x < 0\end{cases}
35
-
```
36
-
37
-
<!-- <div class="equation" align="center" data-raw-text="|x| = \begin{cases} x & \textrm{if}\ x \geq 0 \\ -x & \textrm{if}\ x < 0\end{cases}" data-equation="eq:absolute_value">
@@ -57,88 +42,115 @@ var abs = require( '@stdlib/math/special/abs' );
57
42
58
43
#### abs( x\[, options] )
59
44
60
-
Computes the [absolute value][absolute-value].
45
+
Computes the [absolute value][@stdlib/math/base/special/abs] for each element in an [ndarray][@stdlib/ndarray/ctor].
61
46
62
47
```javascript
63
-
var y =abs( -1.0 );
64
-
// returns 1.0
48
+
var ndarray2array =require( '@stdlib/ndarray/to-array' );
49
+
var array =require( '@stdlib/ndarray/array' );
50
+
51
+
var x =array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] );
52
+
var y =abs( x );
53
+
// returns <ndarray>
54
+
55
+
var arr =ndarray2array( y );
56
+
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ]
65
57
```
66
58
67
59
The function accepts the following arguments:
68
60
69
-
-**x**: input [`ndarray`][@stdlib/ndarray/ctor], array-like object, or number. If provided an [`ndarray`][@stdlib/ndarray/ctor] or array-like object, the function performs element-wise computation.
70
-
-**options**: function options.
61
+
-**x**: input [ndarray][@stdlib/ndarray/ctor].
62
+
-**options**: function options (_optional_).
63
+
64
+
The function accepts the following options:
71
65
72
-
If provided an [`ndarray`][@stdlib/ndarray/ctor], the function returns an [`ndarray`][@stdlib/ndarray/ctor] having the same shape and data type as `x`.
66
+
-**dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. Must be a real-valued or generic [data type][@stdlib/ndarray/dtypes].
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having a [data type][@stdlib/ndarray/dtypes] determined by the function's output data type [policy][@stdlib/ndarray/output-dtype-policies]. To override the default behavior, set the `dtype` option.
73
70
74
71
```javascript
72
+
var ndarray2array =require( '@stdlib/ndarray/to-array' );
75
73
var array =require( '@stdlib/ndarray/array' );
74
+
var getDType =require( '@stdlib/ndarray/dtype' );
76
75
77
-
var x =array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] ); // 2x2
78
-
var y =abs( x );
76
+
var x =array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] );
77
+
var y =abs( x, {
78
+
'dtype':'generic'
79
+
});
79
80
// returns <ndarray>
80
81
81
-
var v =y.get( 0, 1 );
82
-
// returns 2.0
83
-
```
84
-
85
-
If provided an array-like object, the function returns an array-like object having the same length and data type as `x`.
-**dtype**: output array [data type][@stdlib/ndarray/dtypes]. Only applicable when `x` is either an [`ndarray`][@stdlib/ndarray/ctor] or array-like object. By default, the output array data type is inferred from the input array.
102
-
-**order**: output array [order][@stdlib/ndarray/orders]. Only applicable when `x` is an [`ndarray`][@stdlib/ndarray/ctor]. By default, the output array order is inferred from the input array.
103
-
104
-
By default, when provided either an [`ndarray`][@stdlib/ndarray/ctor] or an array-like object, the function returns an object of the same "kind" (either an [`ndarray`][@stdlib/ndarray/ctor] or array-like object, respectively) having the same underlying [data type][@stdlib/ndarray/dtypes]. To specify a different output array [data type][@stdlib/ndarray/dtypes], set the `dtype` option.
89
+
By default, the function returns an [ndarray][@stdlib/ndarray/ctor] having the same [order][@stdlib/ndarray/orders] as the input [ndarray][@stdlib/ndarray/ctor]. To return an [ndarray][@stdlib/ndarray/ctor] having a specific memory layout irrespective of the memory layout of the input [ndarray][@stdlib/ndarray/ctor], set the `order` option.
Computes the [absolute value][absolute-value]and assigns results to a provided output array.
111
+
Computes the [absolute value][@stdlib/math/base/special/abs] for each element in an [ndarray][@stdlib/ndarray/ctor]and assigns results to a provided output [ndarray][@stdlib/ndarray/ctor].
123
112
124
113
```javascript
114
+
var ndarray2array =require( '@stdlib/ndarray/to-array' );
125
115
var array =require( '@stdlib/ndarray/array' );
126
116
127
-
var x =array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] ); // 2x2
128
-
var y =array( [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ] ); // 2x2
117
+
var x =array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] );
118
+
var y =array( [ [ 0.0, 0.0 ], [ 0.0, 0.0 ] ] );
119
+
129
120
var out =abs.assign( x, y );
130
121
// returns <ndarray>
131
122
132
123
var bool = ( out === y );
133
124
// returns true
134
125
135
-
varv=y.get( 0, 1 );
136
-
// returns 2.0
126
+
vararr=ndarray2array( out );
127
+
// returns [ [ 1.0, 2.0 ], [ 3.0, 4.0 ] ]
137
128
```
138
129
139
-
The output array must be the same data "kind" (i.e., [`ndarray`][@stdlib/ndarray/ctor] or array-like object) as the input array. For example, if `x` is an [`ndarray`][@stdlib/ndarray/ctor], `y` must also be an [`ndarray`][@stdlib/ndarray/ctor]. Similarly, if `x` is an array-like object, `y` must also be an array-like object.
130
+
The function accepts the following arguments:
131
+
132
+
-**x**: input [ndarray][@stdlib/ndarray/ctor]. Must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape of the output [ndarray][@stdlib/ndarray/ctor].
133
+
-**y**: output [ndarray][@stdlib/ndarray/ctor].
134
+
135
+
The function supports broadcasting an input [ndarray][@stdlib/ndarray/ctor] to the shape of the output [ndarray][@stdlib/ndarray/ctor] without performing a physical copy of the input [ndarray][@stdlib/ndarray/ctor]'s underlying data.
136
+
137
+
```javascript
138
+
var ndarray2array =require( '@stdlib/ndarray/to-array' );
139
+
var zeros =require( '@stdlib/ndarray/zeros' );
140
+
var array =require( '@stdlib/ndarray/array' );
141
+
142
+
// Create a 2x2 input ndarray:
143
+
var x =array( [ [ -1.0, -2.0 ], [ -3.0, -4.0 ] ] );
@@ -148,6 +160,10 @@ TODO: broadcasting discussion and example(s).
148
160
149
161
<sectionclass="notes">
150
162
163
+
## Notes
164
+
165
+
- The output data type [policy][@stdlib/ndarray/output-dtype-policies] only applies to the main function and specifies that, by default, the function must return an [ndarray][@stdlib/ndarray/ctor] having a real-valued or "generic" [data type][@stdlib/ndarray/dtypes]. For the `assign` method, the output [ndarray][@stdlib/ndarray/ctor] is allowed to have any supported output [data type][@stdlib/ndarray/dtypes].
166
+
151
167
</section>
152
168
153
169
<!-- /.notes -->
@@ -161,34 +177,15 @@ TODO: broadcasting discussion and example(s).
0 commit comments