Auto-generated commit

stdlib-js · Dec 14, 2024 · 5069873 · 5069873
1 parent f14ca10
commit 5069873
Show file tree

Hide file tree

Showing 16 changed files with 3,983 additions and 10 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,7 @@
 
 ##### Features
 
+-   [`dbfd8f5`](https://github.com/stdlib-js/stdlib/commit/dbfd8f5c81d11be2142ebfc4f2f0bb0316ba7478) - add `filterMap` to namespace
 -   [`cbc4d3f`](https://github.com/stdlib-js/stdlib/commit/cbc4d3f7514b7213cad4f9d2ca5d916e13eeffa5) - add `reject` to namespace
 -   [`831de1b`](https://github.com/stdlib-js/stdlib/commit/831de1b4ba21cda245c073a5412bf1a2e9d7598d) - add `map` and `filter` to namespace
 -   [`8b1548f`](https://github.com/stdlib-js/stdlib/commit/8b1548fb45c1ff131f5edac20cb984344a2d28ec) - update namespace TypeScript declarations [(#3190)](https://github.com/stdlib-js/stdlib/pull/3190)
@@ -158,6 +159,28 @@
 
 <!-- /.package -->
 
+<section class="package" id="ndarray-filter-map-unreleased">
+
+#### [@stdlib/ndarray/filter-map](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/filter-map)
+
+<details>
+
+<section class="features">
+
+##### Features
+
+-   [`6ff153f`](https://github.com/stdlib-js/stdlib/commit/6ff153f9023cffac527b3243489e6413e989e940) - add `ndarray/filter-map`
+
+</section>
+
+<!-- /.features -->
+
+</details>
+
+</section>
+
+<!-- /.package -->
+
 <section class="package" id="ndarray-iter-unreleased">
 
 #### [@stdlib/ndarray/iter](https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/ndarray/iter)
@@ -294,6 +317,11 @@ A total of 3 people contributed to this release. Thank you to the following cont
 
 <details>
 
+-   [`dbfd8f5`](https://github.com/stdlib-js/stdlib/commit/dbfd8f5c81d11be2142ebfc4f2f0bb0316ba7478) - **feat:** add `filterMap` to namespace _(by Athan Reines)_
+-   [`6ff153f`](https://github.com/stdlib-js/stdlib/commit/6ff153f9023cffac527b3243489e6413e989e940) - **feat:** add `ndarray/filter-map` _(by Athan Reines)_
+-   [`8d1be60`](https://github.com/stdlib-js/stdlib/commit/8d1be60be03dae4a293d0a2967ab2539d759a498) - **refactor:** remove unnecessary variable _(by Athan Reines)_
+-   [`07c9202`](https://github.com/stdlib-js/stdlib/commit/07c92021666d2b439a239397d54a43e5785b3360) - **refactor:** remove unnecessary variable _(by Athan Reines)_
+-   [`4cc1f54`](https://github.com/stdlib-js/stdlib/commit/4cc1f54e1c601aefcf00bfa03948f2909eba60be) - **docs:** update example _(by Athan Reines)_
 -   [`3cd740e`](https://github.com/stdlib-js/stdlib/commit/3cd740ed3e550ee7411139fef930a96216cff5d9) - **docs:** add example _(by Athan Reines)_
 -   [`855b8c2`](https://github.com/stdlib-js/stdlib/commit/855b8c255abba003e9505aa3a80105a2e2b6b3a7) - **docs:** add example _(by Athan Reines)_
 -   [`47d03ca`](https://github.com/stdlib-js/stdlib/commit/47d03ca557edea6a39c8fa3cc3262ad85d04cd56) - **docs:** add example _(by Athan Reines)_

diff --git a/filter-map/README.md b/filter-map/README.md
@@ -0,0 +1,267 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2024 The Stdlib Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+-->
+
+# filterMap
+
+> Filter and map elements in an input [ndarray][@stdlib/ndarray/ctor] to elements in a new output [ndarray][@stdlib/ndarray/ctor] according to a callback function.
+
+<section class="intro">
+
+</section>
+
+<!-- /.intro -->
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var filterMap = require( '@stdlib/ndarray/filter-map' );
+```
+
+#### filterMap( x\[, options], fcn\[, thisArg] )
+
+Filters and maps elements in an input [ndarray][@stdlib/ndarray/ctor] to elements in a new output [ndarray][@stdlib/ndarray/ctor] according to a callback function.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var ndarray = require( '@stdlib/ndarray/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+function fcn( z ) {
+    if ( z > 5.0 ) {
+        return z * 10.0;
+    }
+}
+
+var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+var shape = [ 2, 3 ];
+var strides = [ 6, 1 ];
+var offset = 1;
+
+var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+// returns <ndarray>
+
+var y = filterMap( x, fcn );
+// returns <ndarray>
+
+var arr = ndarray2array( y );
+// returns [ 80.0, 90.0, 100.0 ]
+```
+
+The function accepts the following arguments:
+
+-   **x**: input [ndarray][@stdlib/ndarray/ctor].
+-   **options**: function options _(optional)_.
+-   **fcn**: callback function.
+-   **thisArg**: callback function execution context _(optional)_.
+
+The function accepts the following options:
+
+-   **dtype**: output ndarray [data type][@stdlib/ndarray/dtypes]. If not specified, the output ndarray [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor].
+-   **order**: index iteration order. By default, the function iterates over elements according to the [layout order][@stdlib/ndarray/orders] of the provided [ndarray][@stdlib/ndarray/ctor]. Accordingly, for row-major input [ndarrays][@stdlib/ndarray/ctor], the last dimension indices increment fastest. For column-major input [ndarrays][@stdlib/ndarray/ctor], the first dimension indices increment fastest. To override the inferred order and ensure that indices increment in a specific manor, regardless of the input [ndarray][@stdlib/ndarray/ctor]'s layout order, explicitly set the iteration order. Note, however, that iterating according to an order which does not match that of the input [ndarray][@stdlib/ndarray/ctor] may, in some circumstances, result in performance degradation due to cache misses. Must be either `'row-major'` or `'column-major'`.
+
+By default, the output ndarray [data type][@stdlib/ndarray/dtypes] is inferred from the input [ndarray][@stdlib/ndarray/ctor]. To return an ndarray with a different [data type][@stdlib/ndarray/dtypes], specify the `dtype` option.
+
+<!-- eslint-disable max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var ndarray = require( '@stdlib/ndarray/ctor' );
+var dtype = require( '@stdlib/ndarray/dtype' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+function fcn( z ) {
+    if ( z > 5.0 ) {
+        return z * 10.0;
+    }
+}
+
+var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+var shape = [ 2, 3 ];
+var strides = [ 6, 1 ];
+var offset = 1;
+
+var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+// returns <ndarray>
+
+var opts = {
+    'dtype': 'float32'
+};
+var y = filterMap( x, opts, fcn );
+// returns <ndarray>
+
+var dt = dtype( y );
+// returns 'float32'
+
+var arr = ndarray2array( y );
+// returns [ 80.0, 90.0, 100.0 ]
+```
+
+To set the callback function execution context, provide a `thisArg`.
+
+<!-- eslint-disable no-invalid-this, max-len -->
+
+```javascript
+var Float64Array = require( '@stdlib/array/float64' );
+var ndarray = require( '@stdlib/ndarray/ctor' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+function fcn( z ) {
+    this.count += 1;
+    if ( z > 5.0 ) {
+        return z * 10.0;
+    }
+}
+
+var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+var shape = [ 2, 3 ];
+var strides = [ 6, 1 ];
+var offset = 1;
+
+var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+// returns <ndarray>
+
+var ctx = {
+    'count': 0
+};
+var y = filterMap( x, fcn, ctx );
+// returns <ndarray>
+
+var arr = ndarray2array( y );
+// returns [ 80.0, 90.0, 100.0 ]
+
+var count = ctx.count;
+// returns 6
+```
+
+The callback function is provided the following arguments:
+
+-   **value**: current array element.
+-   **indices**: current array element indices.
+-   **arr**: the input [ndarray][@stdlib/ndarray/ctor].
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+## Notes
+
+-   The function does **not** perform explicit casting (e.g., from a real-valued floating-point number to a complex floating-point number). Any such casting should be performed by a provided callback function.
+
+    <!-- eslint-disable max-len -->
+
+    ```javascript
+    var Float64Array = require( '@stdlib/array/float64' );
+    var ndarray = require( '@stdlib/ndarray/ctor' );
+    var Complex128 = require( '@stdlib/complex/float64/ctor' );
+    var ndarray2array = require( '@stdlib/ndarray/to-array' );
+
+    function fcn( z ) {
+        if ( z > 5.0 ) {
+            return new Complex128( z, 0.0 );
+        }
+    }
+
+    var buffer = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0 ] );
+    var shape = [ 2, 3 ];
+    var strides = [ 6, 1 ];
+    var offset = 1;
+
+    var x = ndarray( 'float64', buffer, shape, strides, offset, 'row-major' );
+    // returns <ndarray>
+
+    var opts = {
+        'dtype': 'complex128'
+    };
+    var y = filterMap( x, opts, fcn );
+    // returns <ndarray>
+    ```
+
+-   If a provided callback function returns `undefined`, the function skips the respective [ndarray][@stdlib/ndarray/ctor] element. If the callback function returns a value other than `undefined`, the function stores the callback's return value in the output [ndarray][@stdlib/ndarray/ctor].
+
+-   The function **always** returns a one-dimensional [ndarray][@stdlib/ndarray/ctor].
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );
+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var array = require( '@stdlib/ndarray/array' );
+var filterMap = require( '@stdlib/ndarray/filter-map' );
+
+function fcn( v ) {
+    if ( v > 0 ) {
+        return v * 100;
+    }
+}
+
+var buffer = discreteUniform( 10, -100, 100, {
+    'dtype': 'generic'
+});
+var x = array( buffer, {
+    'shape': [ 5, 2 ],
+    'dtype': 'generic'
+});
+console.log( ndarray2array( x ) );
+
+var y = filterMap( x, fcn );
+console.log( ndarray2array( y ) );
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<section class="links">
+
+[@stdlib/ndarray/ctor]: https://github.com/stdlib-js/ndarray/tree/main/ctor
+
+[@stdlib/ndarray/dtypes]: https://github.com/stdlib-js/ndarray/tree/main/dtypes
+
+[@stdlib/ndarray/orders]: https://github.com/stdlib-js/ndarray/tree/main/orders
+
+<!-- <related-links> -->
+
+<!-- </related-links> -->
+
+</section>
+
+<!-- /.links -->