Auto-generated commit

Author: stdlib-bot

CHANGELOG.md

@@ -4,12 +4,14 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2025-07-28)
+## Unreleased (2025-07-29)
 
 <section class="features">
 
 ### Features
 
+-   [`c8567dc`](https://github.com/stdlib-js/stdlib/commit/c8567dc46194708845553af0631c54cc81b25170) - add `rekeyViews` to namespace
+-   [`768090d`](https://github.com/stdlib-js/stdlib/commit/768090def5056f9bb863878fd253b35e23a1f786) - add `array/base/rekey-views`
 -   [`d5a7391`](https://github.com/stdlib-js/stdlib/commit/d5a73912f19ca4825ce2f361fa4a37d193030ee3) - add `rekey` to namespace
 -   [`74dc3c3`](https://github.com/stdlib-js/stdlib/commit/74dc3c37f9b0c66051ba2ab143035cb3a4460970) - add `array/base/rekey`
 -   [`25a75d7`](https://github.com/stdlib-js/stdlib/commit/25a75d7ca2026a01c949a10d04a3a668b40e2e13) - add `groupValuesOnKey` to namespace
@@ -244,6 +246,8 @@ A total of 32 issues were closed in this release:
 
 <details>
 
+-   [`c8567dc`](https://github.com/stdlib-js/stdlib/commit/c8567dc46194708845553af0631c54cc81b25170) - **feat:** add `rekeyViews` to namespace _(by Athan Reines)_
+-   [`768090d`](https://github.com/stdlib-js/stdlib/commit/768090def5056f9bb863878fd253b35e23a1f786) - **feat:** add `array/base/rekey-views` _(by Athan Reines)_
 -   [`d3b0f25`](https://github.com/stdlib-js/stdlib/commit/d3b0f251b37fdc27cd3a02ac794dddba0b2f7b36) - **fix:** correct loop bounds in toJSON method for `nested2views` _(by Philipp Burckhardt)_
 -   [`fbc5910`](https://github.com/stdlib-js/stdlib/commit/fbc5910c2290928c2fdc730a6b166b39e637d304) - **fix:** remove unnecessary loop in toJSON method for entries2views _(by Philipp Burckhardt)_
 -   [`8cdfd62`](https://github.com/stdlib-js/stdlib/commit/8cdfd621717a7a41428526107a42364a921b07ae) - **fix:** ensure proper cache invalidation _(by Athan Reines)_

base/lib/index.js

@@ -1584,6 +1584,15 @@ setReadOnly( ns, 'reject', require( './../../base/reject' ) );
 */
 setReadOnly( ns, 'rekey', require( './../../base/rekey' ) );
 
+/**
+* @name rekeyViews
+* @memberof ns
+* @readonly
+* @type {Function}
+* @see {@link module:@stdlib/array/base/rekey-views}
+*/
+setReadOnly( ns, 'rekeyViews', require( './../../base/rekey-views' ) );
+
 /**
 * @name removeAt
 * @memberof ns

base/rekey-views/README.md

@@ -0,0 +1,143 @@
+<!--
+
+@license Apache-2.0
+
+Copyright (c) 2025 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.
+
+-->
+
+# rekeyViews
+
+> Create an array containing views with renamed keys for every element in a provided array.
+
+<section class="usage">
+
+## Usage
+
+```javascript
+var rekeyViews = require( '@stdlib/array/base/rekey-views' );
+```
+
+#### rekeyViews( arr, mapping )
+
+Returns an array containing views with renamed keys for every element in a provided array.
+
+```javascript
+var x = [
+    {
+        'x': 1,
+        'y': 2
+    },
+    {
+        'x': 3,
+        'y': 4
+    }
+];
+var mapping = {
+    'x': 'a',
+    'y': 'b'
+};
+
+var out = rekeyViews( x, mapping );
+// returns [ <Object>, <Object> ]
+
+var v0 = out[ 0 ].toJSON();
+// returns { 'a': 1, 'b': 2 }
+
+var v1 = out[ 1 ].toJSON();
+// returns { 'a': 3, 'b': 4 }
+
+// Mutate the first element in the input array:
+x[ 0 ].x = 5;
+
+v0 = out[ 0 ].toJSON();
+// returns { 'a': 5, 'b': 2 }
+
+// Set a view property:
+out[ 1 ].b = 'beep';
+
+v1 = out[ 1 ].toJSON();
+// returns { 'a': 3, 'b': 'beep' }
+
+var y = x.slice();
+// returns [ { 'x': 5, 'y': 2 }, { 'x': 3, 'y': 'beep' } ]
+```
+
+The function has the following parameters:
+
+-   **arr**: input array.
+-   **mapping**: object mapping existing keys to new key names.
+
+</section>
+
+<!-- /.usage -->
+
+<section class="notes">
+
+-   The function returns views having **only** those keys which are present in a provided mapping object. Any keys which are **not** present in the provided mapping object, but are present in the original objects, are **omitted** during view creation.
+-   The function assumes that each object has the keys specified in a provided mapping object.
+-   Each view in the returned array shares the same memory as the corresponding elements in the input arrays. Accordingly, mutation of either an array element or a view will mutate the other.
+
+</section>
+
+<!-- /.notes -->
+
+<section class="examples">
+
+## Examples
+
+<!-- eslint no-undef: "error" -->
+
+```javascript
+var discreteUniform = require( '@stdlib/random/base/discrete-uniform' );
+var filledBy = require( '@stdlib/array/base/filled-by' );
+var rekeyViews = require( '@stdlib/array/base/rekey-views' );
+
+function clbk( idx ) {
+    return {
+        'x': idx,
+        'y': discreteUniform( 0, 10 )
+    };
+}
+
+var x = filledBy( 10, clbk );
+var mapping = {
+    'x': 'a',
+    'y': 'b'
+};
+
+var out = rekeyViews( x, mapping );
+// returns [...]
+```
+
+</section>
+
+<!-- /.examples -->
+
+<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
+
+<section class="related">
+
+</section>
+
+<!-- /.related -->
+
+<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
+
+<section class="links">
+
+</section>
+
+<!-- /.links -->

base/rekey-views/benchmark/benchmark.js

@@ -0,0 +1,74 @@
+/**
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench' );
+var isArray = require( '@stdlib/assert/is-array' );
+var filledBy = require( './../../../base/filled-by' );
+var pkg = require( './../package.json' ).name;
+var rekeyViews = require( './../lib' );
+
+
+// FUNCTIONS //
+
+/**
+* Returns an object.
+*
+* @private
+* @param {NonNegativeInteger} idx - element index
+* @returns {Object} object
+*/
+function clbk( idx ) {
+	return {
+		'x': idx,
+		'y': idx
+	};
+}
+
+
+// MAIN //
+
+bench( pkg+':size=100', function benchmark( b ) {
+	var mapping;
+	var x;
+	var i;
+	var v;
+
+	mapping = {
+		'x': 'a',
+		'y': 'b'
+	};
+	x = filledBy( 100, clbk );
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = rekeyViews( x, mapping );
+		if ( typeof v !== 'object' ) {
+			b.fail( 'should return an array' );
+		}
+	}
+	b.toc();
+	if ( !isArray( v ) ) {
+		b.fail( 'should return an array' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});

base/rekey-views/docs/repl.txt

@@ -0,0 +1,43 @@
+
+{{alias}}( arr, mapping )
+    Returns an array containing views with renamed keys for every element in a
+    provided array.
+
+    The function returns views having only those keys which are present in a
+    provided mapping object. Any keys which are not present in the provided
+    mapping object, but are present in the original objects, are omitted during
+    view creation.
+
+    The function assumes that each object has the keys specified in a provided
+    mapping object.
+
+    Each view in the returned array shares the same memory as the corresponding
+    elements in the input arrays. Accordingly, mutation of either an array
+    element or a view will mutate the other.
+
+    Parameters
+    ----------
+    arr: ArrayLikeObject<Object>
+        Input array.
+
+    mapping: Object
+        Object mapping existing keys to new key names.
+
+    Returns
+    -------
+    out: Array<Object>
+        Output array.
+
+    Examples
+    --------
+    > var x = [ { 'x': 1, 'y': 2 }, { 'x': 3, 'y': 4 } ];
+    > var m = { 'x': 'a', 'y': 'b' };
+    > var out = {{alias}}( x, m );
+    > var v = out[ 0 ].toJSON()
+    { 'a': 1, 'b': 2 }
+    > v = out[ 1 ].toJSON()
+    { 'a': 3, 'b': 4 }
+
+    See Also
+    --------
+

base/rekey-views/docs/types/index.d.ts

@@ -0,0 +1,88 @@
+/*
+* @license Apache-2.0
+*
+* Copyright (c) 2025 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.
+*/
+
+// TypeScript Version: 4.1
+
+/// <reference types="@stdlib/types"/>
+
+import { Collection, AccessorArrayLike } from '@stdlib/types/array';
+
+/**
+* Property key.
+*/
+type PropertyKey = string | number | symbol;
+
+/**
+* Returns an array containing views with renamed keys for every element in a provided array.
+*
+* ## Notes
+*
+* -   The function returns views having only those keys which are present in a provided mapping object. Any keys which are not present in the provided mapping object, but are present in the original objects, are omitted during view creation.
+* -   The function assumes that each object has the keys specified in a provided mapping object.
+* -   Each view in the returned array shares the same memory as the corresponding elements in the input arrays. Accordingly, mutation of either an array element or a view will mutate the other.
+*
+* @param arr - input array
+* @param mapping - object mapping existing keys to new key names
+* @returns output array
+*
+* @example
+* var x = [
+*     {
+*         'x': 1,
+*         'y': 2
+*     },
+*     {
+*         'x': 3,
+*         'y': 4
+*     }
+* ];
+* var mapping = {
+*     'x': 'a',
+*     'y': 'b'
+* };
+*
+* var out = rekeyViews( x, mapping );
+* // returns [ <Object>, <Object> ]
+*
+* var v0 = out[ 0 ].toJSON();
+* // returns { 'a': 1, 'b': 2 }
+*
+* var v1 = out[ 1 ].toJSON();
+* // returns { 'a': 3, 'b': 4 }
+*
+* // Mutate the first element in the input array:
+* x[ 0 ].x = 5;
+*
+* v0 = out[ 0 ].toJSON();
+* // returns { 'a': 5, 'b': 2 }
+*
+* // Set a view property:
+* out[ 1 ].b = 'beep';
+*
+* v1 = out[ 1 ].toJSON();
+* // returns { 'a': 3, 'b': 'beep' }
+*
+* var y = x.slice();
+* // returns [ { 'x': 5, 'y': 2 }, { 'x': 3, 'y': 'beep' } ]
+*/
+declare function rekeyViews<T extends Record<PropertyKey, any>, OldKey extends keyof T, Mapping extends Record<OldKey, PropertyKey>>( arr: Collection<T> | AccessorArrayLike<T>, mapping: Mapping ): Array<{ [ K in OldKey as Mapping[K] ]: T[K] }>;
+
+
+// EXPORTS //
+
+export = rekeyViews;