Auto-generated commit

stdlib-bot · stdlib-bot · commit b42e11d2a266 · 2024-11-20T02:59:14.000Z
diff --git a/.github/workflows/test_published_package.yml b/.github/workflows/test_published_package.yml
@@ -0,0 +1,105 @@
+#/
+# @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.
+#/
+
+# Workflow name:
+name: test_published_package
+
+# Workflow triggers:
+on:
+  # Run workflow on a weekly schedule:
+  schedule:
+    # * is a special character in YAML so you have to quote this string
+    - cron:  '6 18 * * 0'
+
+  # Run workflow upon completion of `publish` workflow run:
+  workflow_run:
+    workflows: ["publish"]
+    types: [completed]
+
+  # Allow workflow to be manually run:
+  workflow_dispatch:
+
+# Workflow jobs:
+jobs:
+  test-published:
+    # Define a display name:
+    name: 'Test running examples of published package'
+
+    # Define the type of virtual host machine:
+    runs-on: ubuntu-latest
+
+    # Define environment variables:
+    env:
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+    # Run workflow job if `publish` workflow run is successful or when the workflow is manually run:
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
+
+    # Define the job's steps:
+    steps:
+      # Checkout the repository:
+      - name: 'Checkout repository'
+        uses: actions/checkout@8ade135a41bc03ea155e62e844d188df1ea18608 # v4.1.0
+
+      # Install Node.js:
+      - name: 'Install Node.js'
+        uses: actions/setup-node@b39b52d1213e96004bfcb1c61a8a6fa8ab84f3e8 # v4.0.1
+        with:
+          node-version: 20
+        timeout-minutes: 5
+
+      # Create test directory and run examples:
+      - name: 'Create test directory and run examples'
+        run: |
+          cd ..
+          mkdir test-published
+          cd test-published
+
+          # Copy example file:
+          cp $GITHUB_WORKSPACE/examples/index.js .
+
+          # Create a minimal package.json
+          echo '{
+            "name": "test-published",
+            "version": "1.0.0",
+            "main": "index.js",
+            "dependencies": {}
+          }' > package.json
+
+          # Get package name and modify example file:
+          PACKAGE_NAME=$(jq -r '.name' $GITHUB_WORKSPACE/package.json)
+          ESCAPED_PACKAGE_NAME=$(echo "$PACKAGE_NAME" | sed 's/[\/&]/\\&/g')
+
+          sed -i "s/require( '.\/..\/lib' )/require( '$ESCAPED_PACKAGE_NAME' )/g" index.js
+
+          # Extract and install dependencies:
+          DEPS=$(grep -oP "require\(\s*'([^']+)'\s*\)" index.js | sed "s/require(\s*'//" | sed "s/'\s*)//" | grep -v "^\.")
+          for dep in $DEPS; do
+            npm install $dep --save
+          done
+
+          # Run the example:
+          node index.js
+
+      # Send Slack notification if job fails:
+      - name: 'Send notification to Slack in case of failure'
+        uses: 8398a7/action-slack@28ba43ae48961b90635b50953d216767a6bea486 # v3.16.2
+        with:
+          status: ${{ job.status }}
+          channel: '#npm-ci'
+        if: failure()
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,25 +4,39 @@
 
 <section class="release" id="unreleased">
 
-## Unreleased (2024-11-18)
+## Unreleased (2024-11-20)
 
 <section class="features">
 
 ### Features
 
+-   [`b34732c`](https://github.com/stdlib-js/stdlib/commit/b34732cf655db60fbc798e12952f88c3edb07eaf) - add `at` method to `array/fixed-endian-factory` [(#3184)](https://github.com/stdlib-js/stdlib/pull/3184)
 -   [`956a462`](https://github.com/stdlib-js/stdlib/commit/956a4624c788689b1bca285856b987ea3aa32eb6) - add `forEach` method
 -   [`a3a04e3`](https://github.com/stdlib-js/stdlib/commit/a3a04e32057b878529b86180e38ed3ae383c34ef) - add `array/fixed-endian-factory`
 
 </section>
 
 <!-- /.features -->
 
+<section class="issues">
+
+### Closed Issues
+
+This release closes the following issue:
+
+[#3135](https://github.com/stdlib-js/stdlib/issues/3135)
+
+</section>
+
+<!-- /.issues -->
+
 <section class="commits">
 
 ### Commits
 
 <details>
 
+-   [`b34732c`](https://github.com/stdlib-js/stdlib/commit/b34732cf655db60fbc798e12952f88c3edb07eaf) - **feat:** add `at` method to `array/fixed-endian-factory` [(#3184)](https://github.com/stdlib-js/stdlib/pull/3184) _(by Aayush Khanna, Athan Reines)_
 -   [`956a462`](https://github.com/stdlib-js/stdlib/commit/956a4624c788689b1bca285856b987ea3aa32eb6) - **feat:** add `forEach` method _(by Athan Reines)_
 -   [`b9f3b77`](https://github.com/stdlib-js/stdlib/commit/b9f3b776e5f3d426629b77206b682836fe6b390f) - **refactor:** reduce string literals _(by Athan Reines)_
 -   [`17fa3d2`](https://github.com/stdlib-js/stdlib/commit/17fa3d277b28d85634444424f2af75edf60ab030) - **docs:** fix example _(by Athan Reines)_
@@ -38,8 +52,9 @@
 
 ### Contributors
 
-A total of 1 person contributed to this release. Thank you to this contributor:
+A total of 2 people contributed to this release. Thank you to the following contributors:
 
+-   Aayush Khanna
 -   Athan Reines
 
 </section>
diff --git a/README.md b/README.md
@@ -339,6 +339,38 @@ var v = arr.get( 0 );
 // returns 1.0
 ```
 
+<a name="method-at"></a>
+
+#### TypedArrayFE.prototype.at( i )
+
+Returns an array element located at integer position (index) `i`, with support for both nonnegative and negative integer positions.
+
+```javascript
+var Float64ArrayFE = fixedEndianFactory( 'float64' );
+
+var arr = new Float64ArrayFE( 'little-endian', [ 1.0, 2.0, 3.0 ] );
+
+var out = arr.at( 0 );
+// returns 1.0
+
+out = arr.at( -1 );
+// returns 3.0
+```
+
+If provided an out-of-bounds index, the method returns `undefined`.
+
+```javascript
+var Float64ArrayFE = fixedEndianFactory( 'float64' );
+
+var arr = new Float64ArrayFE( 'little-endian', [ 1.0, 2.0, 3.0 ] );
+
+var v = arr.at( 100 );
+// returns undefined
+
+v = arr.at( -100 );
+// returns undefined
+```
+
 <a name="method-for-each"></a>
 
 #### TypedArrayFE.prototype.forEach( callbackFn\[, thisArg] )
diff --git a/benchmark/benchmark.at.js b/benchmark/benchmark.at.js
@@ -0,0 +1,146 @@
+/**
+* @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.
+*/
+
+'use strict';
+
+// MODULES //
+
+var bench = require( '@stdlib/bench-harness' );
+var isNumber = require( '@stdlib/assert-is-number' ).isPrimitive;
+var pkg = require( './../package.json' ).name;
+var factory = require( './../lib' );
+
+
+// VARIABLES //
+
+var Float64ArrayFE = factory( 'float64' );
+
+
+// MAIN //
+
+bench( pkg+'::nonnegative_indices:at:endianness=little-endian', function benchmark( b ) {
+	var arr;
+	var N;
+	var v;
+	var i;
+
+	arr = [];
+	for ( i = 0; i < 10; i++ ) {
+		arr.push( i );
+	}
+	arr = new Float64ArrayFE( 'little-endian', arr );
+	N = arr.length;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = arr.at( i % N );
+		if ( typeof v !== 'number' ) {
+			b.fail( 'should return a number' );
+		}
+	}
+	b.toc();
+	if ( !isNumber( v ) ) {
+		b.fail( 'should return a number' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::negative_indices:at:endianness=little-endian', function benchmark( b ) {
+	var arr;
+	var N;
+	var v;
+	var i;
+
+	arr = [];
+	for ( i = 0; i < 10; i++ ) {
+		arr.push( i );
+	}
+	arr = new Float64ArrayFE( 'little-endian', arr );
+	N = arr.length;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = arr.at( -( i % N ) - 1 );
+		if ( typeof v !== 'number' ) {
+			b.fail( 'should return a number' );
+		}
+	}
+	b.toc();
+	if ( !isNumber( v ) ) {
+		b.fail( 'should return a number' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::nonnegative_indices:at:endianness=big-endian', function benchmark( b ) {
+	var arr;
+	var N;
+	var v;
+	var i;
+
+	arr = [];
+	for ( i = 0; i < 1000; i++ ) {
+		arr.push( i );
+	}
+	arr = new Float64ArrayFE( 'big-endian', arr );
+	N = arr.length;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = arr.at( i % N );
+		if ( typeof v !== 'number' ) {
+			b.fail( 'should return a number' );
+		}
+	}
+	b.toc();
+	if ( !isNumber( v ) ) {
+		b.fail( 'should return a number' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
+
+bench( pkg+'::negative_indices:at:endianness=big-endian', function benchmark( b ) {
+	var arr;
+	var N;
+	var v;
+	var i;
+
+	arr = [];
+	for ( i = 0; i < 1000; i++ ) {
+		arr.push( i );
+	}
+	arr = new Float64ArrayFE( 'big-endian', arr );
+	N = arr.length;
+
+	b.tic();
+	for ( i = 0; i < b.iterations; i++ ) {
+		v = arr.at( -( i % N ) - 1 );
+		if ( typeof v !== 'number' ) {
+			b.fail( 'should return a number' );
+		}
+	}
+	b.toc();
+	if ( !isNumber( v ) ) {
+		b.fail( 'should return a number' );
+	}
+	b.pass( 'benchmark finished' );
+	b.end();
+});
diff --git a/dist/index.js b/dist/index.js
diff --git a/dist/index.js.map b/dist/index.js.map
diff --git a/lib/main.js b/lib/main.js
@@ -23,6 +23,7 @@
 // MODULES //
 
 var isNonNegativeInteger = require( '@stdlib/assert-is-nonnegative-integer' ).isPrimitive;
+var isInteger = require( '@stdlib/assert-is-integer' ).isPrimitive;
 var isCollection = require( '@stdlib/assert-is-collection' );
 var isArrayBuffer = require( '@stdlib/assert-is-arraybuffer' );
 var isObject = require( '@stdlib/assert-is-object' );
@@ -457,6 +458,36 @@ function factory( dtype ) { // eslint-disable-line max-lines-per-function, stdli
 		return new this( order, args );
 	});
 
+	/**
+	* Returns an array element located at integer position (index) `i`, with support for both nonnegative and negative integer indices.
+	*
+	* @private
+	* @name at
+	* @memberof TypedArray.prototype
+	* @type {Function}
+	* @param {integer} idx - element index
+	* @throws {TypeError} `this` must be a typed array instance
+	* @throws {TypeError} must provide an integer
+	* @returns {(*|void)} array element
+	*/
+	setReadOnly( TypedArray.prototype, 'at', function at( idx ) {
+		var len;
+		if ( !isTypedArray( this ) ) {
+			throw new TypeError( format( 'invalid invocation. `this` is not %s %s.', CHAR2ARTICLE[ dtype[0] ], CTOR_NAME ) );
+		}
+		if ( !isInteger( idx ) ) {
+			throw new TypeError( format( 'invalid argument. Must provide an integer. Value: `%s`.', idx ) );
+		}
+		len = this._length;
+		if ( idx < 0 ) {
+			idx += len;
+		}
+		if ( idx < 0 || idx >= len ) {
+			return;
+		}
+		return this._buffer[ GETTER ]( idx * BYTES_PER_ELEMENT, this._isLE );
+	});
+
 	/**
 	* Pointer to the underlying data buffer.
 	*
diff --git a/package.json b/package.json
@@ -46,6 +46,7 @@
     "@stdlib/assert-is-arraybuffer": "^0.2.2",
     "@stdlib/assert-is-collection": "^0.2.2",
     "@stdlib/assert-is-function": "^0.2.2",
+    "@stdlib/assert-is-integer": "^0.2.2",
     "@stdlib/assert-is-nonnegative-integer": "^0.2.2",
     "@stdlib/assert-is-object": "^0.2.2",
     "@stdlib/assert-is-prototype-of": "^0.2.2",
diff --git a/test/test.at.js b/test/test.at.js
