diff --git a/.editorconfig b/.editorconfig index 0779e8ad978e..dab5d2a638dd 100644 --- a/.editorconfig +++ b/.editorconfig @@ -86,7 +86,6 @@ indent_style = tab [*.{f,f.txt}] indent_style = space indent_size = 2 -insert_final_newline = false # Set properties for shell files: [*.{sh,sh.txt}] diff --git a/.github/workflows/good_first_issue.yml b/.github/workflows/good_first_issue.yml index 730799067755..abe24145bf83 100644 --- a/.github/workflows/good_first_issue.yml +++ b/.github/workflows/good_first_issue.yml @@ -56,7 +56,7 @@ jobs: GH_REPO: ${{ github.repository }} NUMBER: ${{ github.event.issue.number }} BODY: | - # :rotating_light: Important: PLEASE READ :rotating_light: + # :wave: Important: PLEASE READ :wave: This issue has been labeled as a **good first issue** and is available for anyone to work on. diff --git a/.github/workflows/labeler.yml b/.github/workflows/labeler.yml index 62a1404a32bd..bc2ef3f71b37 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/labeler.yml @@ -24,6 +24,7 @@ on: pull_request_target: types: - opened + - closed - synchronize - reopened - edited @@ -64,6 +65,31 @@ jobs: configuration-path: .github/labeler.yml repo-token: ${{ secrets.CHATBOT_GITHUB_TOKEN }} + # Add "First-time Contributor" label if PR is from a first-time contributor: + - name: 'Add "First-time Contributor" label if PR is from a first-time contributor' + if: ${{ github.event.action == 'opened' || github.event.action == 'reopened' }} + # Pin action to full-length commit SHA + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + with: + github-token: ${{ secrets.CHATBOT_GITHUB_TOKEN }} + script: | + const { data: pr } = await github.rest.pulls.get({ + 'owner': context.repo.owner, + 'repo': context.repo.repo, + 'pull_number': context.payload.pull_request.number + }); + if ( pr.author_association === 'FIRST_TIME_CONTRIBUTOR' ) { + const labels = context.payload.pull_request.labels.map( label => label.name ); + if ( !labels.includes( 'First-time Contributor' ) ) { + await github.rest.issues.addLabels({ + 'owner': context.repo.owner, + 'repo': context.repo.repo, + 'issue_number': context.payload.pull_request.number, + 'labels': [ 'First-time Contributor' ] + }); + } + } + # Add "Needs Review" label when PR is opened and not a draft: - name: 'Add "Needs Review" label if PR is opened and not draft' if: ${{ github.event.action == 'opened' && github.event.pull_request.draft == false }} @@ -133,3 +159,37 @@ jobs: console.log( 'Error removing label %s: %s', label, error.message ); } } + + # Remove "First-time Contributor" label from other open PRs of same author if PR is merged: + - name: 'Remove "First-time Contributor" label from other open PRs of same author if PR is merged' + if: ${{ github.event.action == 'closed' && github.event.pull_request.merged == true }} + # Pin action to full length commit SHA + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + with: + github-token: ${{ secrets.CHATBOT_GITHUB_TOKEN }} + script: | + const prAuthor = context.payload.pull_request.user.login; + const { owner, repo } = context.repo; + + // Search for all open PRs from the PR author: + const query = `repo:${owner}/${repo} type:pr state:open author:${prAuthor}`; + const response = await github.rest.search.issuesAndPullRequests({ + 'q': query, + 'per_page': 100 + }); + + const pullRequests = response.data.items; + for ( const pull of pullRequests ) { + if ( pull.user.login === prAuthor ) { + try { + await github.rest.issues.removeLabel({ + 'owner': context.repo.owner, + 'repo': context.repo.repo, + 'issue_number': pull.number, + 'name': 'First-time Contributor' + }); + } catch ( error ) { + console.log( 'Error removing "First-time Contributor" label from PR #%d: %s', pull.number, error.message ); + } + } + } diff --git a/.github/workflows/labeler_needs_changes.yml b/.github/workflows/labeler_needs_changes.yml index f9d1f055af0f..5f92960a9441 100644 --- a/.github/workflows/labeler_needs_changes.yml +++ b/.github/workflows/labeler_needs_changes.yml @@ -52,7 +52,6 @@ jobs: # Pin action to a known commit SHA for reproducibility: uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 with: - github-token: ${{ secrets.CHATBOT_GITHUB_TOKEN }} script: | await github.rest.issues.addLabels({ 'owner': context.repo.owner, diff --git a/.github/workflows/lint_changed_files.yml b/.github/workflows/lint_changed_files.yml index 2872118bcba9..bc91909c277b 100644 --- a/.github/workflows/lint_changed_files.yml +++ b/.github/workflows/lint_changed_files.yml @@ -72,8 +72,21 @@ jobs: node-version: '20' # 'lts/*' timeout-minutes: 5 + # Cache dependencies: + - name: 'Cache dependencies' + # Pin action to full length commit SHA + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + id: cache + with: + path: | + ${{ github.workspace }}/node_modules + key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }} + restore-keys: | + ${{ runner.os }}-node- + # Install dependencies (accounting for possible network failures, etc, when installing node module dependencies): - name: 'Install dependencies' + if: steps.cache.outputs.cache-hit != 'true' run: | make install-node-modules || make install-node-modules || make install-node-modules timeout-minutes: 15 @@ -120,7 +133,7 @@ jobs: - name: 'Lint against EditorConfig' if: success() || failure() run: | - make lint-editorconfig-files FILES="${{ steps.changed-files.outputs.files }}" + make lint-editorconfig-files EDITORCONFIG_FORMAT=github-actions FILES="${{ steps.changed-files.outputs.files }}" # Lint Markdown files: - name: 'Lint Markdown files' diff --git a/.github/workflows/namespace_declarations.yml b/.github/workflows/namespace_declarations.yml index 3a0ee65dfc57..0da71e94c179 100644 --- a/.github/workflows/namespace_declarations.yml +++ b/.github/workflows/namespace_declarations.yml @@ -112,6 +112,15 @@ jobs: - updates namespace TypeScript declarations + ## Reviewer Checklist + + - [ ] **Check the scope of the changes** (following [Conventional Commits](https://www.conventionalcommits.org)): + - Are these **new APIs**? Then this is a `feat`. + - Are these **changes to existing APIs** that could break compatibility? Then this is a `feat!` (i.e., a breaking change). + - Are these **only documentation** changes to existing APIs? Then this is `docs`. + - [ ] Update the PR title to align with the change type (`feat`, `feat!`, or `docs`). + - [ ] Approve the PR once you are confident about the classification and changes made. + commit-message: 'feat: update namespace TypeScript declarations' committer: 'stdlib-bot <82920195+stdlib-bot@users.noreply.github.com>' signoff: true diff --git a/.github/workflows/run_affected_benchmarks.yml b/.github/workflows/run_affected_benchmarks.yml index 268d596f2e19..b2630bb72287 100644 --- a/.github/workflows/run_affected_benchmarks.yml +++ b/.github/workflows/run_affected_benchmarks.yml @@ -35,6 +35,11 @@ on: # List paths for which changes should trigger this workflow: - 'lib/**/benchmark/**' + workflow_dispatch: + inputs: + directories: + description: 'List of changed directories for which to run affected benchmarks (space-separated)' + # Global permissions: permissions: # Allow read-only access to the repository contents: @@ -78,8 +83,21 @@ jobs: node-version: '20' # 'lts/*' timeout-minutes: 5 + # Cache dependencies: + - name: 'Cache dependencies' + # Pin action to full length commit SHA + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + id: cache + with: + path: | + ${{ github.workspace }}/node_modules + key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }} + restore-keys: | + ${{ runner.os }}-node- + # Install dependencies (accounting for possible network failures, etc, when installing node module dependencies): - name: 'Install dependencies' + if: steps.cache.outputs.cache-hit != 'true' run: | make install-node-modules || make install-node-modules || make install-node-modules timeout-minutes: 15 @@ -90,9 +108,10 @@ jobs: make init timeout-minutes: 5 - # Get list of changed files: - - name: 'Get list of changed files' - id: changed-files + # Get list of changed directories from PR and push events: + - name: 'Get list of changed directories' + if: github.event_name != 'workflow_dispatch' + id: changed-directories continue-on-error: true run: | if [ -n "${{ github.event.pull_request.number }}" ]; then @@ -107,24 +126,24 @@ jobs: files=$(git diff --diff-filter=AM --name-only ${{ github.event.before }} ${{ github.event.after }}) fi fi - # Keep only benchmark files: - files=$(echo "$files" | grep -E 'benchmark/' | tr '\n' ' ' | sed 's/ $//') - echo "files=${files}" >> $GITHUB_OUTPUT + directories=$(for file in $files; do dirname $file; done | uniq | tr '\n' ' ' | sed 's/ $//') + echo "directories=${directories}" >> $GITHUB_OUTPUT - # Run JavaScript benchmarks: - - name: 'Run JavaScript benchmarks' + # Get list of changed directories from workflow dispatch event: + - name: 'Get list of changed directories (from user input)' + if: github.event_name == 'workflow_dispatch' + id: changed-directories-user-input run: | - files=$(echo "${{ steps.changed-files.outputs.files }}" | tr ' ' '\n' | grep -E '\.js$' | tr '\n' ' ' | sed 's/ $//') - if [ -n "$files" ]; then - make benchmark-javascript-files FILES="${files}" - fi - timeout-minutes: 30 + echo "directories=${{ github.event.inputs.directories }}" >> $GITHUB_OUTPUT + timeout-minutes: 5 - # Run C benchmarks: - - name: 'Run C benchmarks' + # Run affected benchmarks: + - name: 'Run affected benchmarks' run: | - files=$(echo "${{ steps.changed-files.outputs.files }}" | tr ' ' '\n' | grep -E '\.c$' | sed "s|^|${GITHUB_WORKSPACE}/|" | tr '\n' ' ' | sed 's/ $//') - if [ -n "$files" ]; then - make benchmark-c-files FILES="${files}" + if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then + directories="${{ steps.changed-directories-user-input.outputs.directories }}" + else + directories="${{ steps.changed-directories.outputs.directories }}" fi - timeout-minutes: 15 + . "$GITHUB_WORKSPACE/.github/workflows/scripts/run_affected_benchmarks" "$directories" + timeout-minutes: 30 diff --git a/.github/workflows/run_affected_examples.yml b/.github/workflows/run_affected_examples.yml index 9ac6777c0482..76faa9ad2889 100644 --- a/.github/workflows/run_affected_examples.yml +++ b/.github/workflows/run_affected_examples.yml @@ -79,8 +79,21 @@ jobs: node-version: '20' # 'lts/*' timeout-minutes: 5 + # Cache dependencies: + - name: 'Cache dependencies' + # Pin action to full length commit SHA + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + id: cache + with: + path: | + ${{ github.workspace }}/node_modules + key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }} + restore-keys: | + ${{ runner.os }}-node- + # Install dependencies (accounting for possible network failures, etc, when installing node module dependencies): - name: 'Install dependencies' + if: steps.cache.outputs.cache-hit != 'true' run: | make install-node-modules || make install-node-modules || make install-node-modules timeout-minutes: 15 diff --git a/.github/workflows/run_affected_tests.yml b/.github/workflows/run_affected_tests.yml index 3ca2af62b6c1..0bde9d06f2ad 100644 --- a/.github/workflows/run_affected_tests.yml +++ b/.github/workflows/run_affected_tests.yml @@ -114,8 +114,21 @@ jobs: node-version: '20' # 'lts/*' timeout-minutes: 5 + # Cache dependencies: + - name: 'Cache dependencies' + # Pin action to full length commit SHA + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + id: cache + with: + path: | + ${{ github.workspace }}/node_modules + key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }} + restore-keys: | + ${{ runner.os }}-node- + # Install dependencies (accounting for possible network failures, etc, when installing node module dependencies): - name: 'Install dependencies' + if: steps.cache.outputs.cache-hit != 'true' run: | make install-node-modules || make install-node-modules || make install-node-modules timeout-minutes: 15 diff --git a/.github/workflows/run_tests_coverage.yml b/.github/workflows/run_tests_coverage.yml index d1116c0eb449..de9e8031094d 100644 --- a/.github/workflows/run_tests_coverage.yml +++ b/.github/workflows/run_tests_coverage.yml @@ -120,8 +120,21 @@ jobs: node-version: 20 # 'lts/*' timeout-minutes: 5 + # Cache dependencies: + - name: 'Cache dependencies' + # Pin action to full length commit SHA + uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4.2.0 + id: cache + with: + path: | + ${{ github.workspace }}/node_modules + key: ${{ runner.os }}-node-${{ hashFiles('**/package.json') }} + restore-keys: | + ${{ runner.os }}-node- + # Install dependencies (accounting for possible network failures, etc, when installing node module dependencies): - name: 'Install dependencies' + if: steps.cache.outputs.cache-hit != 'true' run: | make install-node-modules || make install-node-modules || make install-node-modules timeout-minutes: 15 diff --git a/.github/workflows/scripts/run_affected_benchmarks b/.github/workflows/scripts/run_affected_benchmarks new file mode 100755 index 000000000000..acd3e36d88fb --- /dev/null +++ b/.github/workflows/scripts/run_affected_benchmarks @@ -0,0 +1,163 @@ +#!/usr/bin/env bash +# +# @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. + +# Script to run affected benchmarks for a given list of changed paths. +# +# Usage: run_affected_benchmarks path1 [path2 path3 ...] +# +# Arguments: +# +# path1 File name or directory path. +# path2 File name or directory path. +# path3 File name or directory path. +# +# +# Environment variables: +# +# LOG_FILE Log file. +# + +# shellcheck disable=SC2034,SC2153,SC2317 + +# Ensure that the exit status of pipelines is non-zero in the event that at least one of the commands in a pipeline fails: +set -o pipefail + + +# VARIABLES # + +# Get the list of changed files: +changed="$*" + +# Get the path to a log file as the third argument to the build script: +log_file="${LOG_FILE}" + +# Define a heartbeat interval to periodically print messages in order to prevent CI from prematurely ending a build due to long-running commands: +heartbeat_interval='30s' + +# Declare a variable for storing the heartbeat process id: +heartbeat_pid="" + + +# FUNCTIONS # + +# Error handler. +# +# $1 - error status +on_error() { + echo 'ERROR: An error was encountered during execution.' >&2 + cleanup + exit "$1" +} + +# Runs clean-up tasks. +cleanup() { + stop_heartbeat +} + +# Starts a heartbeat. +# +# $1 - heartbeat interval +start_heartbeat() { + echo 'Starting heartbeat...' >&2 + + # Create a heartbeat and send to background: + heartbeat "$1" & + + # Capture the heartbeat pid: + heartbeat_pid=$! + echo "Heartbeat pid: ${heartbeat_pid}" >&2 +} + +# Runs an infinite print loop. +# +# $1 - heartbeat interval +heartbeat() { + while true; do + echo "$(date) - heartbeat..." >&2 + sleep "$1" + done +} + +# Stops the heartbeat print loop. +stop_heartbeat() { + echo 'Stopping heartbeat...' >&2 + kill "${heartbeat_pid}" +} + +# Prints a success message. +print_success() { + echo 'Success!' >&2 +} + +# Main execution sequence. +main() { + start_heartbeat "${heartbeat_interval}" + + # Only keep files which reside in package directories: + changed=$(echo "${changed}" | tr ' ' '\n' | grep '^lib/node_modules/@stdlib') || true + + # Find unique package directories: + directories=$(echo "${changed}" | tr ' ' '\n' | sed -E 's/\/(bin|data|etc|include|lib|src|test)\/?$//' | uniq) + + if [ -z "${directories}" ]; then + echo 'No packages to run benchmarks for.' >&2 + cleanup + print_success + exit 0 + fi + + # Extract package names from changed package directories (e.g., @stdlib/math/base/special/sin) by removing the leading 'lib/node_modules/': + packages=$(echo "${directories}" | sed -E 's/^lib\/node_modules\///') + + # Build native add-ons for packages (if applicable): + for pkg in ${packages}; do + if [ -f "lib/node_modules/${pkg}/binding.gyp" ]; then + NODE_ADDONS_PATTERN="${pkg}" make install-node-addons + fi + done + + # Find all benchmark files in package directories: + js_bench_files=$(find "${directories}" -maxdepth 3 -wholename '**/benchmark/benchmark*.js' | grep -v '/fixtures/' | sort -u | tr '\n' ' ') || true + + # Run JS benchmarks: + if [ -n "${js_bench_files}" ]; then + make benchmark-javascript-files FILES="${js_bench_files}" + else + echo 'No JavaScript benchmarks to run.' >&2 + fi + + # Run C benchmarks: + echo "Finding C benchmark files in ${directories}..." + c_bench_files=$(find "${directories}" -maxdepth 4 -wholename '**/benchmark/c/benchmark*.c' -exec realpath {} \; | grep -v '/fixtures/' | sort -u | tr '\n' ' ') || true + + if [ -n "${c_bench_files}" ]; then + make benchmark-c-files FILES="${c_bench_files}" + else + echo 'No C benchmarks to run.' >&2 + fi + + cleanup + print_success + exit 0 +} + +# Set an error handler to print captured output and perform any clean-up tasks: +trap 'on_error' ERR + +# Run main: +main diff --git a/.github/workflows/slash_commands.yml b/.github/workflows/slash_commands.yml index e6dfe14e1b18..258449d2a2a3 100644 --- a/.github/workflows/slash_commands.yml +++ b/.github/workflows/slash_commands.yml @@ -61,13 +61,7 @@ jobs: - name: 'Add initial reaction' run: | COMMENT="${{ github.event.comment.body }}" - if [[ $COMMENT == "/stdlib help" || \ - $COMMENT == "/stdlib check-files" || \ - $COMMENT == "/stdlib update-copyright-years" || \ - $COMMENT == "/stdlib lint-autofix" || \ - $COMMENT == "/stdlib merge" || \ - $COMMENT == "/stdlib rebase" - ]]; then + if [[ $COMMENT =~ ^/stdlib\ (help|check-files|update-copyright-years|lint-autofix|merge|rebase) ]]; then curl -X POST \ -H "Accept: application/vnd.github.v3+json" \ -H "Authorization: Bearer ${{ secrets.STDLIB_BOT_GITHUB_TOKEN }}" \ diff --git a/.github/workflows/update_contributors.yml b/.github/workflows/update_contributors.yml index 38a808dd44c2..e125883513c1 100644 --- a/.github/workflows/update_contributors.yml +++ b/.github/workflows/update_contributors.yml @@ -105,6 +105,13 @@ jobs: - updates the list of contributors + ## Reviewer Checklist + + - [ ] For any **new contributors**, check if their full names are listed on their GitHub profile or in social links. + - [ ] If so, on the PR branch **update** the `.mailmap` file accordingly to ensure proper attribution. + - [ ] If updating `.mailmap`, **regenerate** the contributors file by running `make update-contributors` on the PR branch afterward. + - [ ] Approve the PR after verifying the changes. + commit-message: 'docs: update list of contributors' committer: 'stdlib-bot <82920195+stdlib-bot@users.noreply.github.com>' signoff: true diff --git a/.mailmap b/.mailmap index 3593db50775e..34b869cf2903 100644 --- a/.mailmap +++ b/.mailmap @@ -9,6 +9,7 @@ # A Aayush Khanna <96649223+aayush0325@users.noreply.github.com> +Aayush Khanna Aayush Khanna aayush0325 Abhijit Raut <121740684+AbhijitRaut04@users.noreply.github.com> @@ -52,6 +53,9 @@ Chinmay Joshi <86140365+JawHawk@users.noreply.github.com> Chinmay J Debashis Maharana <145602692+DevMhrn@users.noreply.github.com> Debashis Maharana DebashisMaharana +Dhruv Arvind Singh <154677013+DhruvArvindSingh@users.noreply.github.com> DhruvArvindSingh +Dhruv Arvind Singh <154677013+DhruvArvindSingh@users.noreply.github.com> Dhruv/ + Dorrin Sotoudeh <59933477+dorrin-sot@users.noreply.github.com> Dorrin Sotoudeh dorrin-sot @@ -216,6 +220,11 @@ Vaibhav Patel <98279986+noobCoderVP@users.noreply.github.com> ProCoderVP Varad Gupta <114755221+vr-varad@users.noreply.github.com> Varad Gupta vr-varad +Vinit Pandit <106718914+MeastroZI@users.noreply.github.com> <106718914+Vinit-Pandit@users.noreply.github.com> + +Vivek Maurya <155618190+vivekmaurya001@users.noreply.github.com> +Vivek Maurya vivekmaurya001 + # Y Yaswanth Kosuru <116426380+yaswanthkosuru@users.noreply.github.com> yaswanth diff --git a/CONTRIBUTORS b/CONTRIBUTORS index 173c07b086cb..aedb14802ac0 100644 --- a/CONTRIBUTORS +++ b/CONTRIBUTORS @@ -27,6 +27,8 @@ Daniel Killenberger Daniel Yu <40680511+Daniel777y@users.noreply.github.com> Debashis Maharana Desh Deepak Kant <118960904+DeshDeepakKant@users.noreply.github.com> +Dev Goel <135586571+corsairier@users.noreply.github.com> +Dhruv Arvind Singh <154677013+DhruvArvindSingh@users.noreply.github.com> Divyansh Seth <59174836+sethdivyansh@users.noreply.github.com> Dominic Lim <46486515+domlimm@users.noreply.github.com> Dominik Moritz @@ -49,6 +51,7 @@ Joey Reed Jordan Gallivan <115050475+Jordan-Gallivan@users.noreply.github.com> Joris Labie Justin Dennison +Karan Anand <119553199+anandkaranubc@users.noreply.github.com> Karthik Prakash <116057817+skoriop@users.noreply.github.com> Kohantika Nath <145763549+kohantikanath@users.noreply.github.com> Krishnendu Das <86651039+itskdhere@users.noreply.github.com> @@ -117,7 +120,7 @@ UtkershBasnet <119008923+UtkershBasnet@users.noreply.github.com> Vaibhav Patel <98279986+noobCoderVP@users.noreply.github.com> Varad Gupta Vinit Pandit <106718914+MeastroZI@users.noreply.github.com> -Vivek maurya <155618190+vivekmaurya001@users.noreply.github.com> +Vivek Maurya Xiaochuan Ye Yaswanth Kosuru <116426380+yaswanthkosuru@users.noreply.github.com> Yernar Yergaziyev diff --git a/NOTICE b/NOTICE index e6e7482f21fd..cbd3a299d947 100644 --- a/NOTICE +++ b/NOTICE @@ -1 +1 @@ -Copyright (c) 2016-2024 The Stdlib Authors. +Copyright (c) 2016-2025 The Stdlib Authors. diff --git a/README.md b/README.md index 98d0d1ce7fa2..403bb4af67ef 100644 --- a/README.md +++ b/README.md @@ -77,9 +77,10 @@ Thank you for being a part of our community! Your support is invaluable to us! ### External Resources -- [**Open Collective**][open-collective-stdlib] -- [**Twitter**][stdlib-twitter] -- [**Gitter**][stdlib-gitter] +- [**Google Calendar**][stdlib-public-calendar]: calendar of public events, including [open office hours][stdlib-office-hours]. +- [**Open Collective**][open-collective-stdlib]: financially support the project. +- [**Twitter**][stdlib-twitter]: follow us on social media. +- [**Gitter**][stdlib-gitter]: chat with project maintainers and other community members. ## Features @@ -182,11 +183,11 @@ While this project's installation instructions defaults to using [npm][npm] for - I would like to include stdlib functionality by just using a `script` tag. - I would like to use ES Modules. - + - Use an individual package's ES Module [build](#install_env_builds_esm). - + - I would like to use a pre-built bundle (possibly via a CDN, such as [unpkg][unpkg] or [jsDelivr][jsdelivr]). - + - Install (or consume via a CDN) an individual package's pre-built UMD [browser bundle](#install_env_builds_umd). - I am interested in using a substantial amount of functionality found in a top-level stdlib namespace and don't want to separately install hundreds of individual packages (e.g., if building an on-line calculator application and wanting all of stdlib's math functionality). @@ -200,9 +201,9 @@ While this project's installation instructions defaults to using [npm][npm] for - I am interested in using various functionality found in stdlib. - Install [individual packages](#install_individual_packages). Installing the entire project is likely unnecessary and will lead to slower installation times. - + - I would like to **vendor** stdlib functionality and avoid dependency trees. - + - Install individual package UMD [bundles](#install_env_builds_nodejs). - I am interested in using a _substantial_ amount of functionality found in a top-level stdlib namespace and don't want to separately install hundreds of individual packages. @@ -611,7 +612,7 @@ See [LICENSE][stdlib-license]. ## Copyright -Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. +Copyright © 2016-2025. The Stdlib [Authors][stdlib-authors]. @@ -658,6 +659,10 @@ Copyright © 2016-2024. The Stdlib [Authors][stdlib-authors]. [![Chat][chat-image]][chat-url] +Have something you want to discuss? In addition to the community chat, we hold regular [office hours][stdlib-office-hours] over video conferencing, which is a great opportunity to ask questions, share ideas, and engage directly with the stdlib team. + +You can also subscribe to our [project calendar][stdlib-public-calendar] to stay informed about the latest public community events. + @@ -779,6 +784,10 @@ Test and build infrastructure is generously provided by the following services: [stdlib-code-coverage]: https://codecov.io/github/stdlib-js/stdlib/branch/develop +[stdlib-public-calendar]: https://calendar.google.com/calendar/embed?src=a72677fe2820c833714b8b9a2aa87393f742bcaf0d0f6c9499eee6661795eae0%40group.calendar.google.com + +[stdlib-office-hours]: https://github.com/stdlib-js/meetings/issues?q=sort%3Aupdated-desc%20is%3Aissue%20is%3Aopen%20label%3A%22Office%20Hours%22 + [open-collective-stdlib]: https://opencollective.com/stdlib [stdlib-twitter]: https://twitter.com/stdlibjs diff --git a/docs/git-notes/02cbff35d876dcea7efd41794f414c7df5eddca4.txt b/docs/git-notes/02cbff35d876dcea7efd41794f414c7df5eddca4.txt new file mode 100644 index 000000000000..ab61fda3aa91 --- /dev/null +++ b/docs/git-notes/02cbff35d876dcea7efd41794f414c7df5eddca4.txt @@ -0,0 +1,14 @@ +--- +type: amend-message +--- +refactor!: update `blas/ext/base/dapx` to follow current project conventions + +BREAKING CHANGE: + +- `c_dapx()` renamed to `stdlib_strided_dapx()` +- `c_dapx_ndarray()` renamed to `stdlib_strided_dapx_ndarray()` + +All downstream usage of the old `c_dapx*` symbols must be updated to use the new symbols. + +PR-URL: https://github.com/stdlib-js/stdlib/pull/4737 +Reviewed-by: Philipp Burckhardt diff --git a/docs/git-notes/133c5394889b68952968cd6f4ff192f9692deb9f.txt b/docs/git-notes/133c5394889b68952968cd6f4ff192f9692deb9f.txt new file mode 100644 index 000000000000..267d726a6755 --- /dev/null +++ b/docs/git-notes/133c5394889b68952968cd6f4ff192f9692deb9f.txt @@ -0,0 +1,10 @@ +--- +type: amend-message +--- +docs: update namespace TypeScript declaration comments + +PR-URL: https://github.com/stdlib-js/stdlib/pull/4487 + +Co-authored-by: Philipp Burckhardt +Reviewed-by: Philipp Burckhardt +Signed-off-by: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> diff --git a/docs/git-notes/4b1f53de18bc03af6439de1e3797d9e222ecdf28.txt b/docs/git-notes/4b1f53de18bc03af6439de1e3797d9e222ecdf28.txt new file mode 100644 index 000000000000..6fcd733a66f1 --- /dev/null +++ b/docs/git-notes/4b1f53de18bc03af6439de1e3797d9e222ecdf28.txt @@ -0,0 +1,10 @@ +--- +type: amend-message +--- +docs: update namespace TypeScript declaration comments + +PR-URL: https://github.com/stdlib-js/stdlib/pull/4518 + +Co-authored-by: Philipp Burckhardt +Reviewed-by: Philipp Burckhardt +Signed-off-by: stdlib-bot <82920195+stdlib-bot@users.noreply.github.com> diff --git a/lib/node_modules/@stdlib/_tools/doctest/compare-values/lib/main.js b/lib/node_modules/@stdlib/_tools/doctest/compare-values/lib/main.js index 8fe537005181..997119c98666 100644 --- a/lib/node_modules/@stdlib/_tools/doctest/compare-values/lib/main.js +++ b/lib/node_modules/@stdlib/_tools/doctest/compare-values/lib/main.js @@ -25,33 +25,57 @@ var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' ); var indexOf = require( '@stdlib/utils/index-of' ); var typeOf = require( '@stdlib/utils/type-of' ); var deepEqual = require( '@stdlib/assert/deep-equal' ); -var isNull = require( '@stdlib/assert/is-null' ); + +// Note: keep in alphabetical order var isArray = require( '@stdlib/assert/is-array' ); -var isNumber = require( '@stdlib/assert/is-number' ); -var isObject = require( '@stdlib/assert/is-object' ); -var isSymbol = require( '@stdlib/assert/is-symbol' ); -var isUndefined = require( '@stdlib/assert/is-undefined' ); -var isObjectArray = require( '@stdlib/assert/is-object-array' ); +var isArrayBuffer = require( '@stdlib/assert/is-arraybuffer' ); +var isBigInt = require( '@stdlib/assert/is-bigint' ); +var isBigInt64Array = require( '@stdlib/assert/is-bigint64array' ); +var isBigUint64Array = require( '@stdlib/assert/is-biguint64array' ); var isBoolean = require( '@stdlib/assert/is-boolean' ); -var isString = require( '@stdlib/assert/is-string' ); -var isRegExp = require( '@stdlib/assert/is-regexp' ); -var isEmptyString = require( '@stdlib/assert/is-empty-string' ); +var isBooleanArray = require( '@stdlib/assert/is-booleanarray' ); +var isBoxedPrimitive = require( '@stdlib/assert/is-boxed-primitive' ); +var isBuffer = require( '@stdlib/assert/is-buffer' ); var isComplex64 = require( '@stdlib/assert/is-complex64' ); -var isComplex128 = require( '@stdlib/assert/is-complex128' ); var isComplex64Array = require( '@stdlib/assert/is-complex64array' ); +var isComplex128 = require( '@stdlib/assert/is-complex128' ); var isComplex128Array = require( '@stdlib/assert/is-complex128array' ); -var isBoxedPrimitive = require( '@stdlib/assert/is-boxed-primitive' ); -var isPrimitive = require( '@stdlib/assert/is-primitive' ); -var isObjectLike = require( '@stdlib/assert/is-object-like' ); +var isComplexTypedArray = require( '@stdlib/assert/is-complex-typed-array' ); +var isDataView = require( '@stdlib/assert/is-dataview' ); +var isDateObject = require( '@stdlib/assert/is-date-object' ); +var isEmptyString = require( '@stdlib/assert/is-empty-string' ); +var isError = require( '@stdlib/assert/is-error' ); +var isEvalError = require( '@stdlib/assert/is-eval-error' ); +var isFloat32Array = require( '@stdlib/assert/is-float32array' ); +var isFloat64Array = require( '@stdlib/assert/is-float64array' ); var isFunction = require( '@stdlib/assert/is-function' ); +var isInt8Array = require( '@stdlib/assert/is-int8array' ); +var isInt16Array = require( '@stdlib/assert/is-int16array' ); +var isInt32Array = require( '@stdlib/assert/is-int32array' ); +var isMultiSlice = require( '@stdlib/assert/is-multi-slice' ); +var isndarrayLike = require( '@stdlib/assert/is-ndarray-like' ); +var isNull = require( '@stdlib/assert/is-null' ); +var isNumber = require( '@stdlib/assert/is-number' ); +var isObject = require( '@stdlib/assert/is-object' ); +var isObjectArray = require( '@stdlib/assert/is-object-array' ); +var isObjectLike = require( '@stdlib/assert/is-object-like' ); +var isPrimitive = require( '@stdlib/assert/is-primitive' ); +var isReferenceError = require( '@stdlib/assert/is-reference-error' ); +var isRangeError = require( '@stdlib/assert/is-range-error' ); +var isRegExp = require( '@stdlib/assert/is-regexp' ); +var isSlice = require( '@stdlib/assert/is-slice' ); +var isString = require( '@stdlib/assert/is-string' ); +var isSymbol = require( '@stdlib/assert/is-symbol' ); +var isSyntaxError = require( '@stdlib/assert/is-syntax-error' ); var isTypedArray = require( '@stdlib/assert/is-typed-array' ); -var isError = require( '@stdlib/assert/is-error' ); var isTypeError = require( '@stdlib/assert/is-type-error' ); -var isSyntaxError = require( '@stdlib/assert/is-syntax-error' ); -var isReferenceError = require( '@stdlib/assert/is-reference-error' ); +var isUint8Array = require( '@stdlib/assert/is-uint8array' ); +var isUint8ClampedArray = require( '@stdlib/assert/is-uint8clampedarray' ); +var isUint16Array = require( '@stdlib/assert/is-uint16array' ); +var isUint32Array = require( '@stdlib/assert/is-uint32array' ); +var isUndefined = require( '@stdlib/assert/is-undefined' ); var isURIError = require( '@stdlib/assert/is-uri-error' ); -var isEvalError = require( '@stdlib/assert/is-eval-error' ); -var isRangeError = require( '@stdlib/assert/is-range-error' ); + var startsWith = require( '@stdlib/string/starts-with' ); var contains = require( '@stdlib/assert/contains' ); var endsWith = require( '@stdlib/string/ends-with' ); @@ -61,6 +85,12 @@ var replace = require( '@stdlib/string/replace' ); var trim = require( '@stdlib/string/trim' ); var PINF = require( '@stdlib/constants/float64/pinf' ); var NINF = require( '@stdlib/constants/float64/ninf' ); +var real = require( '@stdlib/complex/float64/real' ); +var imag = require( '@stdlib/complex/float64/imag' ); +var realf = require( '@stdlib/complex/float32/real' ); +var imagf = require( '@stdlib/complex/float32/imag' ); +var reinterpretComplex = require( '@stdlib/strided/base/reinterpret-complex' ); +var copyArray = require( '@stdlib/array/base/copy' ); var createAnnotationValue = require( '@stdlib/_tools/doctest/create-annotation-value' ); var parse = require( './parse.js' ); @@ -159,82 +189,189 @@ function checkPrimitive( actual, expected ) { * @returns {boolean} boolean indicating whether type annotation matches the actual output */ function checkForPlaceholders( actual, expected ) { + // Note: keep in alphabetical order... switch ( expected ) { + case '': + return isArray( actual ); + case '': + return isArrayBuffer( actual ); + case '': + return isBigInt( actual ); + case '': + return isBigInt64Array( actual ); + case '': + return isBigUint64Array( actual ); case '': case '': return isBoolean( actual ); - case '': - case '': - return isString( actual ); - case '': - case '': - return isNumber( actual ); - case '': - case '': - return isSymbol( actual ); - case '': - return isObjectArray( actual ); - case '': - case '': - return isObject( actual ); - case '': - return isArray( actual ); + case '': + return isBooleanArray( actual ); + case '': + return isBuffer( actual ); case '': return isComplex64( actual ); - case '': - return isComplex128( actual ); case '': return isComplex64Array( actual ); + case '': + return isComplex128( actual ); case '': return isComplex128Array( actual ); + case '': + return isDataView( actual ); + case '': + return isDateObject( actual ); case '': return isError( actual ); - case '': - return isTypeError( actual ); - case '': - return isSyntaxError( actual ); - case '': - return isReferenceError( actual ); - case '': - return isURIError( actual ); case '': return isEvalError( actual ); + case '': + return isFloat32Array( actual ); + case '': + return isFloat64Array( actual ); + case '': + return isFunction( actual ); + case '': + return isInt8Array( actual ); + case '': + return isInt16Array( actual ); + case '': + return isInt32Array( actual ); + case '': + return isMultiSlice( actual ); + case '': + return isndarrayLike( actual ); + case '': + case '': + return isNumber( actual ); + case '': // note: exception to alphabetical rule + case '': + return isObject( actual ); + case '': + return isObjectArray( actual ); case '': return isRangeError( actual ); + case '': + return isRegExp( actual ); + case '': + return isReferenceError( actual ); + case '': + return isSlice( actual ); + case '': + case '': + return isString( actual ); + case '': + case '': + return isSymbol( actual ); + case '': + return isSyntaxError( actual ); + case '': + return isTypeError( actual ); + case '': + return isTypedArray( actual ); + case '': + return isUint8Array( actual ); + case '': + return isUint8ClampedArray( actual ); + case '': + return isUint16Array( actual ); + case '': + return isUint32Array( actual ); + case '': + return isURIError( actual ); default: - // Uknown type, let it slide... + // Unknown type, let it slide... + + // TODO: should we compare constructor names here at a minimum? or perhaps walk the prototype tree and compare constructor names to determine whether a value is an instance of? return true; } } /** -* For a typed array, if the return annotation asserts deep instance equality, check whether it corresponds to the actual value; otherwise, check whether the return annotation signals the correct type. +* Compares a list of expected entries with a list of actual values. +* +* @private +* @param {Collection} actual - list of actual values +* @param {Collection} expected - list of expected values +* @returns {(string|null)} result +*/ +function compareEntries( actual, expected ) { + var i; + if ( actual.length !== expected.length ) { + return 'Expected entries ['+expected+'], but observed ['+actual+']'; + } + for ( i = 0; i < expected.length; i++ ) { + if ( !checkPrimitive( actual[ i ], String( expected[ i ] ) ) ) { + return 'Expected entries ['+expected+'], but observed ['+actual+']'; + } + } + return null; +} + +/** +* Checks whether a complex number matches the expected return annotation. * * @private * @param {*} actual - actual return value * @param {string} expected - return value annotation -* @returns {(string|null)} error message in case the annotation and value do not match, `null` otherwise +* @returns {(string|null)} error message or null +*/ +function checkComplex( actual, expected ) { + var entries; + var match; + var type; + + match = RE_INSTANCE_ANNOTATION.exec( expected ); + if ( match ) { + type = match[ 1 ]; + entries = match[ 2 ]; + if ( actual.constructor.name !== type ) { + return 'Expected instance type <'+type+'>, but observed <'+actual.constructor.name+'>'; + } + if ( entries ) { + if ( isComplex128( actual ) ) { + actual = [ real( actual ), imag( actual ) ]; + } else if ( isComplex64( actual ) ) { + actual = [ realf( actual ), imagf( actual ) ]; + } + return compareEntries( actual, parse( entries ) ); + } + return null; + } + return 'Complex numbers should be documented using instance annotation'; +} + +/** +* Checks whether a typed array matches the expected return annotation. +* +* ## Notes +* +* - If the return annotation asserts deep instance equality, check whether it corresponds to the actual value. +* - Otherwise, check whether the return annotation signals the correct type. +* +* @private +* @param {*} actual - actual return value +* @param {string} expected - return value annotation +* @returns {(string|null)} error message or null */ function checkTypedArrays( actual, expected ) { var entries; var match; var type; - var i; match = RE_INSTANCE_ANNOTATION.exec( expected ); if ( match ) { type = match[ 1 ]; entries = match[ 2 ]; if ( actual.constructor.name !== type ) { - return 'Expected instance type <'+actual.constructor.name+'>, but observed <'+type+'>'; + return 'Expected instance type <'+type+'>, but observed <'+actual.constructor.name+'>'; } if ( entries ) { - entries = parse( entries ); - for ( i = 0; i < entries.length; i++ ) { - if ( !checkPrimitive( actual[ i ], String( entries[ i ] ) ) ) { - return 'Expected array entries ['+entries+'], but observed ['+actual+']'; - } + if ( isComplexTypedArray( actual ) ) { + actual = reinterpretComplex( actual, 0 ); + } else if ( isBooleanArray( actual ) ) { + actual = copyArray( actual ); } + return compareEntries( actual, parse( entries ) ); } return null; } @@ -353,7 +490,6 @@ function compareValues( actual, expected ) { // Early return since we cannot compare actual value to return annotation value: return null; } - if ( startsWith( expected, '<' ) && endsWith( expected, '>' ) ) { if ( !checkForPlaceholders( actual, expected ) ) { return 'Expected a '+expected+', but received: `'+actual+'`'; @@ -385,28 +521,35 @@ function compareValues( actual, expected ) { if ( !checkPrimitive( actual, expected ) ) { return 'Displayed return value is `'+expected+'`, but expected `'+actual+'` instead'; } + return null; } - else if ( isTypedArray( actual ) ) { + if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) { return checkTypedArrays( actual, expected ); } if ( isArray( actual ) ) { if ( !checkArray( actual, expected ) ) { return 'Displayed return value is `'+expected+'`, but expected `'+createAnnotationValue( actual )+'` instead'; } + return null; } - else if ( isRegExp( actual ) ) { + if ( isComplex64( actual ) || isComplex128( actual ) ) { + return checkComplex( actual, expected ); + } + if ( isRegExp( actual ) ) { actual = actual.toString(); if ( actual !== expected ) { return 'Displayed return value is `'+expected+'`, but expected `'+actual+'` instead'; } + return null; } - else if ( isFunction( actual ) ) { + if ( isFunction( actual ) ) { actual = actual.toString(); if ( actual !== expected ) { return 'Displayed return value is `'+expected+'`, but expected `'+actual+'` instead'; } + return null; } - else if ( isObjectLike( actual ) ) { + if ( isObjectLike( actual ) ) { if ( !contains( expected, '...' ) ) { try { expectedValue = parse( expected ); @@ -419,6 +562,7 @@ function compareValues( actual, expected ) { return 'Displayed return value is `'+expected+'`, but expected `'+actualString+'` instead'; } } + return null; } return null; } diff --git a/lib/node_modules/@stdlib/_tools/doctest/compare-values/test/test.js b/lib/node_modules/@stdlib/_tools/doctest/compare-values/test/test.js index 99c125c0d734..8e0aff9d4741 100644 --- a/lib/node_modules/@stdlib/_tools/doctest/compare-values/test/test.js +++ b/lib/node_modules/@stdlib/_tools/doctest/compare-values/test/test.js @@ -29,6 +29,8 @@ var Complex64 = require( '@stdlib/complex/float32/ctor' ); var Complex128 = require( '@stdlib/complex/float64/ctor' ); var Complex64Array = require( '@stdlib/array/complex64' ); var Complex128Array = require( '@stdlib/array/complex128' ); +var BooleanArray = require( '@stdlib/array/bool' ); +var ArrayBuffer = require( '@stdlib/array/buffer' ); var compareValues = require( './../lib' ); @@ -42,6 +44,7 @@ function createErrorMessage( actual, expected ) { // TESTS // tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); t.strictEqual( typeof compareValues, 'function', 'main export is a function' ); t.end(); }); @@ -290,24 +293,78 @@ tape( 'the function compares a typed array and a corresponding return annotation actual = new Float64Array( [ 0, 2, 3 ] ); expected = '[ 0, 2, 2 ]'; - msg = 'Expected array entries [0,2,2], but observed [0,2,3]'; + msg = 'Expected entries [0,2,2], but observed [0,2,3]'; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); actual = new Float64Array( [ 0, 2, 3 ] ); expected = '[ 0, 2, 2 ]'; - msg = 'Expected instance type , but observed '; + msg = 'Expected instance type , but observed '; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); buf = new Float32Array( [ 1.0, -1.0, 2.0, -2.0 ] ); actual = new Complex64Array( buf ); - expected = ''; + expected = '[ 1.0, -1.0, 2.0, -2.0 ]'; t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); buf = new Float64Array( [ 1.0, -1.0, 2.0, -2.0 ] ); actual = new Complex128Array( buf ); - expected = ''; + expected = '[ 1.0, -1.0, 2.0, -2.0 ]'; t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); + buf = new Float64Array( [ 1.0, -1.0, 2.0, -2.0 ] ); + actual = new Complex128Array( buf ); + expected = '[ 1.0, 1.0, 2.0, 2.0 ]'; + msg = 'Expected entries [1,1,2,2], but observed [1,-1,2,-2]'; + t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); + + actual = new BooleanArray( [ true, false, true, false ] ); + expected = '[ true, false, true, false ]'; + t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); + + actual = new BooleanArray( [ true, false, true, false ] ); + expected = '[ true, true, true, true ]'; + msg = 'Expected entries [true,true,true,true], but observed [true,false,true,false]'; + t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); + + t.end(); +}); + +tape( 'the function compares a complex number and a corresponding return annotation', function test( t ) { + var expected; + var actual; + var msg; + + actual = new Complex64( 2.0, 3.0 ); + expected = ''; + t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); + + actual = new Complex64( 2.0, 3.0 ); + expected = '[ 2.0, 3.0 ]'; + t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); + + actual = new Complex64( 2.0, 3.0 ); + expected = '[ 2.0, 4.0 ]'; + msg = 'Expected entries [2,4], but observed [2,3]'; + t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); + + actual = new Complex128( 2.0, 3.0 ); + expected = ''; + t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); + + actual = new Complex128( 2.0, 3.0 ); + expected = '[ 2.0, 3.0 ]'; + t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); + + actual = new Complex128( 2.0, 3.0 ); + expected = '[ 2.0, 4.0 ]'; + msg = 'Expected entries [2,4], but observed [2,3]'; + t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); + + actual = new Complex64( 2.0, 3.0 ); + expected = '[ 2.0, 3.0 ]'; + msg = 'Expected instance type , but observed '; + t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); + t.end(); }); @@ -344,12 +401,12 @@ tape( 'the function compares a value with a type equality return annotation', fu msg = 'Expected a , but received: `0`'; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); - actual = new Complex64( 2.0, 3.0 ); - expected = ''; + actual = new ArrayBuffer( 10 ); + expected = ''; t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); - actual = new Complex128( 2.0, 3.0 ); - expected = ''; + actual = compareValues; + expected = ''; t.strictEqual( compareValues( actual, expected ), null, 'returns null' ); t.end(); @@ -369,7 +426,7 @@ tape( 'the function differentiates between boxed and primitive values', function msg = 'Expected a , but received an unboxed primitive: `2.3`'; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); - actual = new Number( 2.3 ); // eslint-disable-line no-new-wrappers + actual = new Number( 2.3 ); expected = ''; msg = 'Expected a , but received a boxed primitive: `2.3`'; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); @@ -393,7 +450,7 @@ tape( 'the function differentiates between boxed and primitive values', function msg = 'Expected a , but received an unboxed primitive: `false`'; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); - actual = new Boolean( false ); // eslint-disable-line no-new-wrappers + actual = new Boolean( false ); expected = ''; msg = 'Expected a , but received a boxed primitive: `false`'; t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' ); diff --git a/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/lib/main.js b/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/lib/main.js index 8ba4676ad4b8..50d00828fab5 100644 --- a/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/lib/main.js +++ b/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/lib/main.js @@ -20,27 +20,33 @@ // MODULES // +// Note: keep in alphabetical order +var isArray = require( '@stdlib/assert/is-array' ); +var isBoolean = require( '@stdlib/assert/is-boolean' ); +var isBooleanArray = require( '@stdlib/assert/is-booleanarray' ); var isBoxedPrimitive = require( '@stdlib/assert/is-boxed-primitive' ); -var isTypedArray = require( '@stdlib/assert/is-typed-array' ); +var isComplexTypedArray = require( '@stdlib/assert/is-complex-typed-array' ); +var isError = require( '@stdlib/assert/is-error' ); var isInfinite = require( '@stdlib/assert/is-infinite' ); -var isPrimitive = require( '@stdlib/assert/is-primitive' ); -var isBoolean = require( '@stdlib/assert/is-boolean' ); var isInteger = require( '@stdlib/assert/is-integer' ); +var isnan = require( '@stdlib/assert/is-nan' ); +var isNull = require( '@stdlib/assert/is-null' ); var isNumber = require( '@stdlib/assert/is-number' ); -var isString = require( '@stdlib/assert/is-string' ); -var isArray = require( '@stdlib/assert/is-array' ); -var isError = require( '@stdlib/assert/is-error' ); var isObject = require( '@stdlib/assert/is-object' ); +var isPrimitive = require( '@stdlib/assert/is-primitive' ); var isRegExp = require( '@stdlib/assert/is-regexp' ); +var isString = require( '@stdlib/assert/is-string' ); +var isTypedArray = require( '@stdlib/assert/is-typed-array' ); var isUndefined = require( '@stdlib/assert/is-undefined' ); -var isNull = require( '@stdlib/assert/is-null' ); -var isnan = require( '@stdlib/assert/is-nan' ); + var capitalize = require( '@stdlib/string/capitalize' ); var roundn = require( '@stdlib/math/base/special/roundn' ); var floor = require( '@stdlib/math/base/special/floor' ); var constructorName = require( '@stdlib/utils/constructor-name' ); var objectKeys = require( '@stdlib/utils/keys' ); var typeOf = require( '@stdlib/utils/type-of' ); +var reinterpretComplex = require( '@stdlib/strided/base/reinterpret-complex' ); +var copyArray = require( '@stdlib/array/base/copy' ); var validate = require( './validate.js' ); @@ -131,35 +137,43 @@ function genericAnnotation( actual, opts ) { var keys; var out; var end; + var f; var i; if ( isPrimitive( actual ) ) { return primitiveAnnotation( actual, opts ); } - if ( isTypedArray( actual ) ) { + if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) { out = '<'+actual.constructor.name+'>'; if ( actual.length === 0 ) { out += '[]'; return out; } + f = numberAnnotation; + if ( isComplexTypedArray( actual ) ) { + actual = reinterpretComplex( actual, 0 ); + } else if ( isBooleanArray( actual ) ) { + actual = copyArray( actual ); + f = genericAnnotation; + } out += '[ '; - out += numberAnnotation( actual[ 0 ], opts ); + out += f( actual[ 0 ], opts ); if ( actual.length > opts.numel ) { end = floor( opts.numel / 2 ); for ( i = 1; i < end; i++ ) { out += ', '; - out += numberAnnotation( actual[ i ], opts ); + out += f( actual[ i ], opts ); } out += ', ...'; for ( i = actual.length - end; i < actual.length; i++ ) { out += ', '; - out += numberAnnotation( actual[ i ], opts ); + out += f( actual[ i ], opts ); } } else { for ( i = 1; i < actual.length; i++ ) { out += ', '; - out += numberAnnotation( actual[ i ], opts ); + out += f( actual[ i ], opts ); } } out += ' ]'; diff --git a/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/test/test.js b/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/test/test.js index f57e20fa3471..0030afdb4f45 100644 --- a/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/test/test.js +++ b/lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/test/test.js @@ -32,12 +32,14 @@ var Complex64 = require( '@stdlib/complex/float32/ctor' ); var Complex128 = require( '@stdlib/complex/float64/ctor' ); var Complex64Array = require( '@stdlib/array/complex64' ); var Complex128Array = require( '@stdlib/array/complex128' ); +var BooleanArray = require( '@stdlib/array/bool' ); var createAnnotationValue = require( './../lib' ); // TESTS // tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); t.strictEqual( typeof createAnnotationValue, 'function', 'main export is a function' ); t.end(); }); @@ -203,7 +205,7 @@ tape( 'the function creates a type annotation value for boxed primitives', funct 'type': true }; - val = new Number( 1/3 ); // eslint-disable-line no-new-wrappers + val = new Number( 1/3 ); expected = ''; t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' ); @@ -211,7 +213,7 @@ tape( 'the function creates a type annotation value for boxed primitives', funct expected = ''; t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' ); - val = new Boolean( false ); // eslint-disable-line no-new-wrappers + val = new Boolean( false ); expected = ''; t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' ); @@ -307,6 +309,20 @@ tape( 'the function creates a deep instance equality annotation value for typed expected = '[ ~0.333, 0.5, 1 ]'; t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' ); + val = new Complex64Array( [ 1, 2, 3, 4, 5, 6, 7, 8 ] ); + opts = { + 'numel': 6 + }; + expected = '[ 1, 2, 3, ..., 6, 7, 8 ]'; + t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' ); + + val = new BooleanArray( [ true, false, true, false ] ); + opts = { + 'numel': 6 + }; + expected = '[ true, false, true, false ]'; + t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' ); + t.end(); }); @@ -384,6 +400,10 @@ tape( 'the function creates a type annotation for class instances', function tes expected = ''; t.strictEqual( createAnnotationValue( actual, opts ), expected, 'returns expected value' ); + actual = new BooleanArray( [ true, false, true, false ] ); + expected = ''; + t.strictEqual( createAnnotationValue( actual, opts ), expected, 'returns expected value' ); + actual = noop; expected = ''; t.strictEqual( createAnnotationValue( actual, opts ), expected, 'returns expected value' ); diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/new-cap-error/test/fixtures/invalid.js b/lib/node_modules/@stdlib/_tools/eslint/rules/new-cap-error/test/fixtures/invalid.js index d0f73ad34ce0..8092a66b83e1 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/new-cap-error/test/fixtures/invalid.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/new-cap-error/test/fixtures/invalid.js @@ -83,7 +83,7 @@ test = { '', 'function sqrt( x ) {', ' if ( x < 0 ) {', - ' throw TypeError( \'must provide a non-negative number\' );', + ' throw TypeError( \'must provide a nonnegative number\' );', ' }', ' return Math.sqrt( x );', '}' @@ -99,7 +99,7 @@ test = { '', 'function sqrt( x ) {', ' if ( x < 0 ) {', - ' throw new TypeError( \'must provide a non-negative number\' );', + ' throw new TypeError( \'must provide a nonnegative number\' );', ' }', ' return Math.sqrt( x );', '}' diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/README.md b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/README.md index c6bc1a2448a0..2d4de5d418cc 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/README.md +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/README.md @@ -38,7 +38,7 @@ var rule = require( '@stdlib/_tools/eslint/rules/repl-namespace-order' ); #### rule -[ESLint rule][eslint-rules] to enforce that packages are added to a REPL namespace object in alphabetical order according to alias (namespace key). +[ESLint rule][eslint-rules] to enforce that packages are added to a REPL namespace object in alphabetical order according to alias (namespace key). **Bad**: @@ -117,8 +117,6 @@ var result; var code; code = [ - '/* eslint-enable stdlib/repl-namespace-order */', - '', '/* When adding names to the namespace, ensure that they are added in alphabetical order according to alias (namespace key). */', '', 'ns.push({', diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/examples/index.js b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/examples/index.js index 789d95dc36b9..fcff2649d875 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/examples/index.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/examples/index.js @@ -26,8 +26,6 @@ var result; var code; code = [ - '/* eslint-enable stdlib/repl-namespace-order */', - '', '/* When adding names to the namespace, ensure that they are added in alphabetical order according to alias (namespace key). */', '', 'ns.push({', diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/lib/main.js b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/lib/main.js index f451656f02a5..a75bd4e8b64d 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/lib/main.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/lib/main.js @@ -37,43 +37,81 @@ var OPTS_COMPARE = { * @returns {Object} validators */ function main( context ) { + var expressions; var prevAlias; - return { - 'ObjectExpression': validate - }; + expressions = []; /** - * Checks whether packages are added to a REPL namespace object in alphabetical order according to alias (namespace key). + * Extracts the alias value from a given node. * * @private - * @param {ASTNode} node - node to examine + * @param {ASTNode} node - node containing properties to search + * @returns {string} alias value */ - function validate( node ) { - var properties; + function getAlias( node ) { + var props; var alias; - var prop; var i; - properties = node.properties; - for ( i = 0; i < properties.length; i++ ) { - prop = properties[ i ]; - if ( prop.key.value === 'alias' ) { - alias = prop.value.value; + props = node.properties; + for ( i = 0; i < props.length; i++ ) { + if ( props[ i ].key.value === 'alias' ) { + alias = props[ i ].value.value; if ( alias ) { - if ( - prevAlias && - alias.localeCompare( prevAlias, 'en', OPTS_COMPARE ) < 0 ) - { - report( prevAlias, alias, node ); - } else { - prevAlias = alias; - } + return alias; } } } } + /** + * Compares two nodes and determines their order based on the alias property. + * + * @private + * @param {ASTNode} a - first node + * @param {ASTNode} b - second node + * @returns {number} number indicating sort order + */ + function sortExpressions( a, b ) { + var aliasA = getAlias( a.arguments[ 0 ] ); + var aliasB = getAlias( b.arguments[ 0 ] ); + return aliasA.localeCompare( aliasB, 'en', OPTS_COMPARE ); + } + + /** + * Fixes the lint error by reordering the packages. + * + * @private + * @param {Function} fixer - ESLint fixer + * @returns {(Object|null)} fix or null + */ + function fix( fixer ) { + var replacingText; + var startRange; + var endRange; + var sorted; + var source; + var txt; + var i; + + source = context.getSourceCode(); + replacingText = ''; + startRange = expressions[0].range[ 0 ]; + endRange = expressions[ expressions.length - 1 ].range[ 1 ]; + + sorted = expressions.slice().sort( sortExpressions ); + + for ( i = 0; i < sorted.length; i++ ) { + txt = source.getText( sorted[ i ] ); + replacingText += txt; + if ( i < sorted.length - 1 ) { + replacingText += ';\n\n'; + } + } + return fixer.replaceTextRange( [ startRange, endRange ], replacingText ); // eslint-disable-line max-len + } + /** * Reports the error message. * @@ -85,9 +123,62 @@ function main( context ) { function report( last, current, node ) { context.report({ 'node': node, - 'message': '"'+current+'" should come before "'+last+'"' + 'message': '"'+current+'" should come before "'+last+'"', + 'fix': fix }); } + + /** + * Checks whether the packages are added to a REPL namespace object in alphabetical order according to alias (namespace key). + * + * @private + */ + function validate() { + var alias; + var i; + + for ( i = 0; i < expressions.length; i++ ) { + alias = getAlias( expressions[ i ].arguments[ 0 ] ); + if ( + prevAlias && + alias.localeCompare( prevAlias, 'en', OPTS_COMPARE ) < 0 + ) { + report( prevAlias, alias, expressions[ i ].arguments[ 0 ] ); + } else { + prevAlias = alias; + } + } + } + + /** + * Collects all expressions which add a package to a REPL namespace. + * + * @private + * @param {ASTNode} node - node to examine + */ + function collectExpressions( node ) { + var object; + var alias; + + if ( + node.callee.type === 'MemberExpression' && + node.callee.object.name === 'ns' && + node.callee.property.name === 'push' + ) { + object = node.arguments[ 0 ]; + if ( object.type === 'ObjectExpression' ) { + alias = getAlias( object ); + if ( alias ) { + expressions.push( node ); + } + } + } + } + + return { + 'CallExpression': collectExpressions, + 'Program:exit': validate + }; } @@ -95,9 +186,11 @@ function main( context ) { rule = { 'meta': { + 'type': 'suggestion', 'docs': { 'description': 'enforce that packages are added to a REPL namespace object in alphabetical order according to alias (namespace key)' }, + 'fixable': 'code', 'schema': [] }, 'create': main diff --git a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/test/fixtures/invalid.js b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/test/fixtures/invalid.js index ca56212d2543..babaf0a3aad2 100644 --- a/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/test/fixtures/invalid.js +++ b/lib/node_modules/@stdlib/_tools/eslint/rules/repl-namespace-order/test/fixtures/invalid.js @@ -58,12 +58,67 @@ test = { 'message': '"hasInt8ArraySupport" should come before "hasMapSupport"', 'type': 'ObjectExpression' } - ] + ], + 'output': [ + 'ns.push({', + ' \'alias\': \'hasInt8ArraySupport\',', + ' \'path\': \'@stdlib/assert/has-int8array-support\',', + ' \'value\': require( \'@stdlib/assert/has-int8array-support\' ),', + ' \'type\': \'Function\',', + ' \'related\': []', + '});', + '', + 'ns.push({', + ' \'alias\': \'hasInt32ArraySupport\',', + ' \'path\': \'@stdlib/assert/has-int32array-support\',', + ' \'value\': require( \'@stdlib/assert/has-int32array-support\' ),', + ' \'type\': \'Function\',', + ' \'related\': []', + '});', + '', + 'ns.push({', + ' \'alias\': \'hasMapSupport\',', + ' \'path\': \'@stdlib/assert/has-map-support\',', + ' \'value\': require( \'@stdlib/assert/has-map-support\' ),', + ' \'type\': \'Function\',', + ' \'related\': []', + '});' + ].join( '\n' ) }; invalid.push( test ); test = { 'code': [ + 'ns.push({', + ' \'alias\': \'pop\',', + ' \'path\': \'@stdlib/utils/pop\',', + ' \'value\': require( \'@stdlib/utils/pop\' ),', + ' \'type\': \'Function\',', + ' \'related\': [', + ' \'@stdlib/utils/push\',', + ' \'@stdlib/utils/shift\',', + ' \'@stdlib/utils/unshift\'', + ' ]', + '});', + '', + 'ns.push({', + ' \'alias\': \'pluck\',', + ' \'path\': \'@stdlib/utils/pluck\',', + ' \'value\': require( \'@stdlib/utils/pluck\' ),', + ' \'type\': \'Function\',', + ' \'related\': [', + ' \'@stdlib/utils/deep-pluck\',', + ' \'@stdlib/utils/pick\'', + ' ]', + '});' + ].join( '\n' ), + 'errors': [ + { + 'message': '"pluck" should come before "pop"', + 'type': 'ObjectExpression' + } + ], + 'output': [ 'ns.push({', ' \'alias\': \'pluck\',', ' \'path\': \'@stdlib/utils/pluck\',', @@ -86,14 +141,9 @@ test = { ' \'@stdlib/utils/unshift\'', ' ]', '});' - ].join( '\n' ), - 'errors': [ - { - 'message': '"hasInt32ArraySupport" should come before "hasMapSupport"', - 'type': 'ObjectExpression' - } - ] + ].join( '\n' ) }; +invalid.push( test ); test = { 'code': [ @@ -122,7 +172,28 @@ test = { 'message': '"AFINN_96" should come before "AFINN_111"', 'type': 'ObjectExpression' } - ] + ], + 'output': [ + 'ns.push({', + ' \'alias\': \'AFINN_96\',', + ' \'path\': \'@stdlib/datasets/afinn-96\',', + ' \'value\': require( \'@stdlib/datasets/afinn-96\' ),', + ' \'type\': \'Function\',', + ' \'related\': [', + ' \'@stdlib/datasets/afinn-111\'', + ' ]', + '});', + '', + 'ns.push({', + ' \'alias\': \'AFINN_111\',', + ' \'path\': \'@stdlib/datasets/afinn-111\',', + ' \'value\': require( \'@stdlib/datasets/afinn-111\' ),', + ' \'type\': \'Function\',', + ' \'related\': [', + ' \'@stdlib/datasets/afinn-96\'', + ' ]', + '});' + ].join( '\n' ) }; invalid.push( test ); diff --git a/lib/node_modules/@stdlib/array/base/README.md b/lib/node_modules/@stdlib/array/base/README.md index f9ded497e442..197c6de8c5ff 100644 --- a/lib/node_modules/@stdlib/array/base/README.md +++ b/lib/node_modules/@stdlib/array/base/README.md @@ -77,8 +77,15 @@ The namespace exports the following: - [`bbinary4d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-binary4d]: apply a binary callback to elements in two broadcasted nested input arrays and assign results to elements in a four-dimensional nested output array. - [`bbinary5d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-binary5d]: apply a binary callback to elements in two broadcasted nested input arrays and assign results to elements in a five-dimensional nested output array. - [`bquaternary2d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-quaternary2d]: apply a quaternary callback to elements in four broadcasted nested input arrays and assign results to elements in a two-dimensional nested output array. +- [`bquaternary3d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-quaternary3d]: apply a quaternary callback to elements in four broadcasted input arrays and assign results to elements in a three-dimensional nested output array. +- [`bquaternary4d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-quaternary4d]: apply a quaternary callback to elements in four broadcasted input arrays and assign results to elements in a four-dimensional nested output array. +- [`bquaternary5d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-quaternary5d]: apply a quaternary callback to elements in four broadcasted input arrays and assign results to elements in a five-dimensional nested output array. - [`bquinary2d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-quinary2d]: apply a quinary callback to elements in five broadcasted nested input arrays and assign results to elements in a two-dimensional nested output array. +- [`bquinary4d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-quinary4d]: apply a quinary callback to elements in five broadcasted input arrays and assign results to elements in a four-dimensional nested output array. - [`bternary2d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-ternary2d]: apply a ternary callback to elements in three broadcasted nested input arrays and assign results to elements in a two-dimensional nested output array. +- [`bternary3d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-ternary3d]: apply a ternary callback to elements in three broadcasted nested input arrays and assign results to elements in a three-dimensional nested output array. +- [`bternary4d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-ternary4d]: apply a ternary callback to elements in three broadcasted nested input arrays and assign results to elements in a four-dimensional nested output array. +- [`bternary5d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-ternary5d]: apply a ternary callback to elements in three broadcasted nested input arrays and assign results to elements in a five-dimensional nested output array. - [`bunary2d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-unary2d]: apply a unary callback to elements in a broadcasted nested input array and assign results to elements in a two-dimensional nested output array. - [`bunary3d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-unary3d]: apply a unary callback to elements in a broadcasted nested input array and assign results to elements in a three-dimensional nested output array. - [`bunary4d( arrays, shapes, fcn )`][@stdlib/array/base/broadcasted-unary4d]: apply a unary callback to elements in a broadcasted nested input array and assign results to elements in a four-dimensional nested output array. @@ -102,6 +109,7 @@ The namespace exports the following: - [`every( x )`][@stdlib/array/base/every]: test whether all elements in an array are truthy. - [`fancySliceAssign( x, y, s, strict )`][@stdlib/array/base/fancy-slice-assign]: assign element values from a broadcasted input array to corresponding elements in an output array. - [`fancySlice( x, s, strict )`][@stdlib/array/base/fancy-slice]: return a shallow copy of a portion of an array. +- [`fill( x, value, start, end )`][@stdlib/array/base/fill]: fill all elements within a portion of an array with a specified value. - [`filledBy( len, clbk[, thisArg] )`][@stdlib/array/base/filled-by]: create a filled "generic" array according to a provided callback function. - [`filled( value, len )`][@stdlib/array/base/filled]: create a filled "generic" array. - [`filled2dBy( shape, clbk[, thisArg] )`][@stdlib/array/base/filled2d-by]: create a filled two-dimensional nested array according to a provided callback function. @@ -144,6 +152,7 @@ The namespace exports the following: - [`groupValues( x, groups )`][@stdlib/array/base/group-values]: group elements as arrays associated with distinct keys. - [`incrspace( start, stop, increment )`][@stdlib/array/base/incrspace]: generate a linearly spaced numeric array according to a provided increment. - [`indexOf( x, searchElement, fromIndex, equalNaNs )`][@stdlib/array/base/index-of]: return the index of the first element which equals a provided search element. +- [`indicesComplement( N, indices )`][@stdlib/array/base/indices-complement]: return the complement of a list of array indices. - [`join( x, separator )`][@stdlib/array/base/join]: return a string created by joining array elements using a specified separator. - [`lastIndexOf( x, searchElement, fromIndex, equalNaNs )`][@stdlib/array/base/last-index-of]: return the index of the last element which equals a provided search element. - [`last( x )`][@stdlib/array/base/last]: return the last element of an array-like object. @@ -156,11 +165,19 @@ The namespace exports the following: - [`minSignedIntegerDataType( value )`][@stdlib/array/base/min-signed-integer-dtype]: determine the minimum array data type for storing a provided signed integer value. - [`minUnsignedIntegerDataType( value )`][@stdlib/array/base/min-unsigned-integer-dtype]: determine the minimum array data type for storing a provided unsigned integer value. - [`mskbinary2d( arrays, shape, fcn )`][@stdlib/array/base/mskbinary2d]: apply a binary callback to elements in two two-dimensional nested input arrays according to elements in a two-dimensional nested mask array and assign results to elements in a two-dimensional nested output array. +- [`mskbinary3d( arrays, shape, fcn )`][@stdlib/array/base/mskbinary3d]: apply a binary callback to elements in two three-dimensional nested input arrays according to elements in a three-dimensional nested mask array and assign results to elements in a three-dimensional nested output array. +- [`mskbinary4d( arrays, shape, fcn )`][@stdlib/array/base/mskbinary4d]: apply a binary callback to elements in two four-dimensional nested input arrays according to elements in a four-dimensional nested mask array and assign results to elements in a four-dimensional nested output array. +- [`mskbinary5d( arrays, shape, fcn )`][@stdlib/array/base/mskbinary5d]: apply a binary callback to elements in two five-dimensional nested input arrays according to elements in a five-dimensional nested mask array and assign results to elements in a five-dimensional nested output array. +- [`mskfilterMap( x, mask, clbk[, thisArg] )`][@stdlib/array/base/mskfilter-map]: apply a mask and a callback function to a provided input array. - [`mskfilter( x, mask )`][@stdlib/array/base/mskfilter]: apply a mask to a provided input array. +- [`mskfilter2( x, y, mask )`][@stdlib/array/base/mskfilter2]: apply a mask to two provided input arrays in a single pass. +- [`mskfiltern( x, [...arrays,] mask )`][@stdlib/array/base/mskfiltern]: apply a mask to one or more provided input arrays in a single pass. - [`mskput( x, mask, values, mode )`][@stdlib/array/base/mskput]: replace elements of an array with provided values according to a provided mask array. - [`mskreject( x, mask )`][@stdlib/array/base/mskreject]: apply a mask to a provided input array. - [`mskunary2d( arrays, shape, fcn )`][@stdlib/array/base/mskunary2d]: apply a unary callback to elements in a two-dimensional nested input array according to elements in a two-dimensional nested mask array and assign results to elements in a two-dimensional nested output array. - [`mskunary3d( arrays, shape, fcn )`][@stdlib/array/base/mskunary3d]: apply a unary callback to elements in a three-dimensional nested input array according to elements in a three-dimensional nested mask array and assign results to elements in a three-dimensional nested output array. +- [`mskunary4d( arrays, shape, fcn )`][@stdlib/array/base/mskunary4d]: apply a unary callback to elements in a four-dimensional nested input array according to elements in a four-dimensional nested mask array and assign results to elements in a four-dimensional nested output array. +- [`mskunary5d( arrays, shape, fcn )`][@stdlib/array/base/mskunary5d]: apply a unary callback to elements in a five-dimensional nested input array according to elements in a five-dimensional nested mask array and assign results to elements in a five-dimensional nested output array. - [`nCartesianProduct( x1, x2[, ...xN] )`][@stdlib/array/base/n-cartesian-product]: return the n-fold Cartesian product. - [`noneByRight( x, predicate[, thisArg] )`][@stdlib/array/base/none-by-right]: test whether all elements in an array fail a test implemented by a predicate function, iterating from right to left. - [`noneBy( x, predicate[, thisArg] )`][@stdlib/array/base/none-by]: test whether all elements in an array fail a test implemented by a predicate function. @@ -188,6 +205,8 @@ The namespace exports the following: - [`resolveGetter( x )`][@stdlib/array/base/resolve-getter]: return an accessor function for retrieving an element from an array-like object. - [`resolveSetter( x )`][@stdlib/array/base/resolve-setter]: return an accessor function for setting an element in an array-like object. - [`reverse( x )`][@stdlib/array/base/reverse]: reverse an array in-place. +- [`scatterFilled( fill, len, indices, values, mode )`][@stdlib/array/base/scatter-filled]: scatter a list of provided values to specified indices in a new filled "generic" array. +- [`scattered( len, indices, values, mode )`][@stdlib/array/base/scattered]: scatter a list of provided values to specified indices in a new zero-filled "generic" array. - [`setter( dtype )`][@stdlib/array/base/setter]: return an accessor function for setting an element in an indexed array-like object. - [`slice( x, start, end )`][@stdlib/array/base/slice]: return a shallow copy of a portion of an array. - [`strided2array2d( x, shape, strides, offset )`][@stdlib/array/base/strided2array2d]: convert a strided array to a two-dimensional nested array. @@ -195,6 +214,7 @@ The namespace exports the following: - [`strided2array4d( x, shape, strides, offset )`][@stdlib/array/base/strided2array4d]: convert a strided array to a four-dimensional nested array. - [`strided2array5d( x, shape, strides, offset )`][@stdlib/array/base/strided2array5d]: convert a strided array to a five-dimensional nested array. - [`takeIndexed( x, indices )`][@stdlib/array/base/take-indexed]: take elements from an indexed array. +- [`takeIndexed2( x, y, indices )`][@stdlib/array/base/take-indexed2]: take elements from two indexed arrays in a single pass. - [`take( x, indices, mode )`][@stdlib/array/base/take]: take elements from an array. - [`take2d( x, indices, dimension, mode )`][@stdlib/array/base/take2d]: take elements from a two-dimensional nested array. - [`take3d( x, indices, dimension, mode )`][@stdlib/array/base/take3d]: take elements from a three-dimensional nested array. @@ -207,8 +227,11 @@ The namespace exports the following: - [`toReversed( x )`][@stdlib/array/base/to-reversed]: return a new array with elements in reverse order. - [`unary2dBy( arrays, shape, fcn, clbk[, thisArg] )`][@stdlib/array/base/unary2d-by]: apply a unary function to each element retrieved from a two-dimensional nested input array according to a callback function and assign results to elements in a two-dimensional nested output array. - [`unary2d( arrays, shape, fcn )`][@stdlib/array/base/unary2d]: apply a unary callback to elements in a two-dimensional nested input array and assign results to elements in a two-dimensional nested output array. +- [`unary3dBy( arrays, shape, fcn, clbk[, thisArg] )`][@stdlib/array/base/unary3d-by]: apply a unary function to each element retrieved from a three-dimensional nested input array according to a callback function and assign results to elements in a three-dimensional nested output array. - [`unary3d( arrays, shape, fcn )`][@stdlib/array/base/unary3d]: apply a unary callback to elements in a three-dimensional nested input array and assign results to elements in a three-dimensional nested output array. +- [`unary4dBy( arrays, shape, fcn, clbk[, thisArg] )`][@stdlib/array/base/unary4d-by]: apply a unary function to each element retrieved from a four-dimensional nested input array according to a callback function and assign results to elements in a four-dimensional nested output array. - [`unary4d( arrays, shape, fcn )`][@stdlib/array/base/unary4d]: apply a unary callback to elements in a four-dimensional nested input array and assign results to elements in a four-dimensional nested output array. +- [`unary5dBy( arrays, shape, fcn, clbk[, thisArg] )`][@stdlib/array/base/unary5d-by]: apply a unary function to each element retrieved from a five-dimensional nested input array according to a callback function and assign results to elements in a five-dimensional nested output array. - [`unary5d( arrays, shape, fcn )`][@stdlib/array/base/unary5d]: apply a unary callback to elements in a five-dimensional nested input array and assign results to elements in a five-dimensional nested output array. - [`unarynd( arrays, shape, fcn )`][@stdlib/array/base/unarynd]: apply a unary callback to elements in an n-dimensional nested input array and assign results to elements in an n-dimensional nested output array. - [`unitspace( start, stop )`][@stdlib/array/base/unitspace]: generate a linearly spaced numeric array whose elements increment by 1. @@ -344,10 +367,24 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/broadcasted-quaternary2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-quaternary2d +[@stdlib/array/base/broadcasted-quaternary3d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-quaternary3d + +[@stdlib/array/base/broadcasted-quaternary4d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-quaternary4d + +[@stdlib/array/base/broadcasted-quaternary5d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-quaternary5d + [@stdlib/array/base/broadcasted-quinary2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-quinary2d +[@stdlib/array/base/broadcasted-quinary4d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-quinary4d + [@stdlib/array/base/broadcasted-ternary2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-ternary2d +[@stdlib/array/base/broadcasted-ternary3d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-ternary3d + +[@stdlib/array/base/broadcasted-ternary4d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-ternary4d + +[@stdlib/array/base/broadcasted-ternary5d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-ternary5d + [@stdlib/array/base/broadcasted-unary2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-unary2d [@stdlib/array/base/broadcasted-unary3d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/broadcasted-unary3d @@ -394,6 +431,8 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/fancy-slice]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/fancy-slice +[@stdlib/array/base/fill]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/fill + [@stdlib/array/base/filled-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/filled-by [@stdlib/array/base/filled]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/filled @@ -478,6 +517,8 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/index-of]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/index-of +[@stdlib/array/base/indices-complement]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/indices-complement + [@stdlib/array/base/join]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/join [@stdlib/array/base/last-index-of]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/last-index-of @@ -502,8 +543,20 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/mskbinary2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskbinary2d +[@stdlib/array/base/mskbinary3d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskbinary3d + +[@stdlib/array/base/mskbinary4d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskbinary4d + +[@stdlib/array/base/mskbinary5d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskbinary5d + +[@stdlib/array/base/mskfilter-map]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskfilter-map + [@stdlib/array/base/mskfilter]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskfilter +[@stdlib/array/base/mskfilter2]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskfilter2 + +[@stdlib/array/base/mskfiltern]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskfiltern + [@stdlib/array/base/mskput]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskput [@stdlib/array/base/mskreject]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskreject @@ -512,6 +565,10 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/mskunary3d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskunary3d +[@stdlib/array/base/mskunary4d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskunary4d + +[@stdlib/array/base/mskunary5d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/mskunary5d + [@stdlib/array/base/n-cartesian-product]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/n-cartesian-product [@stdlib/array/base/none-by-right]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/none-by-right @@ -566,6 +623,10 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/reverse]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/reverse +[@stdlib/array/base/scatter-filled]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/scatter-filled + +[@stdlib/array/base/scattered]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/scattered + [@stdlib/array/base/setter]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/setter [@stdlib/array/base/slice]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/slice @@ -580,6 +641,8 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/take-indexed]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/take-indexed +[@stdlib/array/base/take-indexed2]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/take-indexed2 + [@stdlib/array/base/take]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/take [@stdlib/array/base/take2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/take2d @@ -604,10 +667,16 @@ var squared = ns.map2d( arr2d, [ 2, 3 ], randu ); [@stdlib/array/base/unary2d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary2d +[@stdlib/array/base/unary3d-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary3d-by + [@stdlib/array/base/unary3d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary3d +[@stdlib/array/base/unary4d-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary4d-by + [@stdlib/array/base/unary4d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary4d +[@stdlib/array/base/unary5d-by]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary5d-by + [@stdlib/array/base/unary5d]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unary5d [@stdlib/array/base/unarynd]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/unarynd diff --git a/lib/node_modules/@stdlib/array/base/assert/README.md b/lib/node_modules/@stdlib/array/base/assert/README.md index a5407b5b4ae1..3b38be66f5c6 100644 --- a/lib/node_modules/@stdlib/array/base/assert/README.md +++ b/lib/node_modules/@stdlib/array/base/assert/README.md @@ -67,6 +67,7 @@ The namespace exports the following: - [`isSafeDataTypeCast( from, to )`][@stdlib/array/base/assert/is-safe-data-type-cast]: determine whether an array data type can be safely cast to another array data type. - [`isSameKindDataTypeCast( from, to )`][@stdlib/array/base/assert/is-same-kind-data-type-cast]: determine whether an array data type can be safely cast to, or is of the same "kind" as, another array data type. - [`isSignedIntegerDataType( value )`][@stdlib/array/base/assert/is-signed-integer-data-type]: test if an input value is a supported array signed integer data type. +- [`isSortedAscending( x )`][@stdlib/array/base/assert/is-sorted-ascending]: test if an array is sorted in ascending order. - [`isUnsignedIntegerDataType( value )`][@stdlib/array/base/assert/is-unsigned-integer-data-type]: test if an input value is a supported array unsigned integer data type. @@ -218,6 +219,8 @@ console.log( 'arr4 is complex typed array: ' + ns.isComplexTypedArray( arr4 ) ); [@stdlib/array/base/assert/is-signed-integer-data-type]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/assert/is-signed-integer-data-type +[@stdlib/array/base/assert/is-sorted-ascending]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/assert/is-sorted-ascending + [@stdlib/array/base/assert/is-unsigned-integer-data-type]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/base/assert/is-unsigned-integer-data-type diff --git a/lib/node_modules/@stdlib/array/base/assert/contains/lib/index.js b/lib/node_modules/@stdlib/array/base/assert/contains/lib/index.js index 6c6862997d16..4ef6bd9590a3 100644 --- a/lib/node_modules/@stdlib/array/base/assert/contains/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/assert/contains/lib/index.js @@ -30,6 +30,8 @@ * // returns true */ +// MODULES // + var setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); var main = require( './main.js' ); var factory = require( './factory.js' ); diff --git a/lib/node_modules/@stdlib/array/base/assert/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/assert/docs/types/index.d.ts index 3bf8ec2445c0..8a8285f76340 100644 --- a/lib/node_modules/@stdlib/array/base/assert/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/assert/docs/types/index.d.ts @@ -42,6 +42,7 @@ import isRealFloatingPointDataType = require( '@stdlib/array/base/assert/is-real import isSafeDataTypeCast = require( '@stdlib/array/base/assert/is-safe-data-type-cast' ); import isSameKindDataTypeCast = require( '@stdlib/array/base/assert/is-same-kind-data-type-cast' ); import isSignedIntegerDataType = require( '@stdlib/array/base/assert/is-signed-integer-data-type' ); +import isSortedAscending = require( '@stdlib/array/base/assert/is-sorted-ascending' ); import isUnsignedIntegerDataType = require( '@stdlib/array/base/assert/is-unsigned-integer-data-type' ); /** @@ -689,6 +690,38 @@ interface Namespace { */ isSignedIntegerDataType: typeof isSignedIntegerDataType; + /** + * Tests if an array is sorted in ascending order. + * + * @param x - input array + * @returns boolean indicating if an array is sorted in ascending order + * + * @example + * var out = ns.isSortedAscending( [ 1, 2, 3 ] ); + * // returns true + * + * @example + * var out = ns.isSortedAscending( [ 3, 2, 1 ] ); + * // returns false + * + * @example + * var out = ns.isSortedAscending( [ 3, 3, 3 ] ); + * // returns true + * + * @example + * var out = ns.isSortedAscending( [ 3 ] ); + * // returns true + * + * @example + * var out = ns.isSortedAscending( [] ); + * // returns false + * + * @example + * var out = ns.isSortedAscending( [ 1, 3, 2 ] ); + * // returns false + */ + isSortedAscending: typeof isSortedAscending; + /** * Tests whether an input value is a supported array unsigned integer data type. * diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/README.md b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/README.md new file mode 100644 index 000000000000..797c484f80d4 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/README.md @@ -0,0 +1,133 @@ + + +# isSortedAscending + +> Test if an array is sorted in ascending order. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var isSortedAscending = require( '@stdlib/array/base/assert/is-sorted-ascending' ); +``` + +#### isSortedAscending( x ) + +Tests if an array is sorted in ascending order. + +```javascript +var out = isSortedAscending( [ 1, 2, 3 ] ); +// returns true + +out = isSortedAscending( [ 3, 2, 1 ] ); +// returns false +``` + +If provided an empty array, the function returns `false`. + +```javascript +var out = isSortedAscending( [] ); +// returns false +``` + +
+ + + + + +
+ +
+ + + + + +
+ +## Examples + + + +```javascript +var AccessorArray = require( '@stdlib/array/base/accessor' ); +var isSortedAscending = require( '@stdlib/array/base/assert/is-sorted-ascending' ); + +var x = new AccessorArray( [ 1, 2, 3, 4 ] ); +var bool = isSortedAscending( x ); +// returns true + +x = new AccessorArray( [ 1, 1, 1, 1 ] ); +bool = isSortedAscending( x ); +// returns true + +x = new AccessorArray( [ 1 ] ); +bool = isSortedAscending( x ); +// returns true + +x = new AccessorArray( [ 1, 3, 2, 4 ] ); +bool = isSortedAscending( x ); +// returns false + +x = new AccessorArray( [ 4, 3, 2, 1 ] ); +bool = isSortedAscending( x ); +// returns false +``` + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/benchmark/benchmark.accessors.length.js b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/benchmark/benchmark.accessors.length.js new file mode 100644 index 000000000000..7d45939737c9 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/benchmark/benchmark.accessors.length.js @@ -0,0 +1,97 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var AccessorArray = require( '@stdlib/array/base/accessor' ); +var pkg = require( './../package.json' ).name; +var isSortedAscending = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = new AccessorArray( zeroTo( len ) ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = isSortedAscending( x ); + if ( typeof out !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( !isBoolean( out ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + + f = createBenchmark( len ); + bench( pkg+'::accessors:len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/benchmark/benchmark.length.js new file mode 100644 index 000000000000..d09cc387375c --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/benchmark/benchmark.length.js @@ -0,0 +1,96 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var pkg = require( './../package.json' ).name; +var isSortedAscending = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = zeroTo( len ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = isSortedAscending( x ); + if ( typeof out !== 'boolean' ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( !isBoolean( out ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + + f = createBenchmark( len ); + bench( pkg+':len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/repl.txt b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/repl.txt new file mode 100644 index 000000000000..4a0363b93571 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/repl.txt @@ -0,0 +1,26 @@ + +{{alias}}( x ) + Tests if an array is sorted in ascending order. + + The function returns `false` if provided an empty array. + + Parameters + ---------- + x: ArrayLikeObject + Input array. + + Returns + ------- + out: boolean + Boolean indicating if an array is sorted in ascending order. + + Examples + -------- + > var out = {{alias}}( [ 1, 2, 3 ] ) + true + > out = {{alias}}( [ 3, 2, 1 ] ) + false + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/types/index.d.ts new file mode 100644 index 000000000000..f5bcfeadf160 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/types/index.d.ts @@ -0,0 +1,60 @@ +/* +* @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 + +/// + +import { Collection, AccessorArrayLike } from '@stdlib/types/array'; + +/** +* Tests if an array is sorted in ascending order. +* +* @param x - input array +* @returns boolean indicating if an array is sorted in ascending order +* +* @example +* var out = isSortedAscending( [ 1, 2, 3 ] ); +* // returns true +* +* @example +* var out = isSortedAscending( [ 3, 2, 1 ] ); +* // returns false +* +* @example +* var out = isSortedAscending( [ 3, 3, 3 ] ); +* // returns true +* +* @example +* var out = isSortedAscending( [ 3 ] ); +* // returns true +* +* @example +* var out = isSortedAscending( [] ); +* // returns false +* +* @example +* var out = isSortedAscending( [ 1, 3, 2 ] ); +* // returns false +*/ +declare function isSortedAscending( x: Collection | AccessorArrayLike ): boolean; + + +// EXPORTS // + +export = isSortedAscending; diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/types/test.ts new file mode 100644 index 000000000000..65843227bcc4 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/docs/types/test.ts @@ -0,0 +1,42 @@ +/* +* @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. +*/ + +import isSortedAscending = require( './index' ); + + +// TESTS // + +// The function returns a boolean... +{ + isSortedAscending( [ 1, 2, 3 ] ); // $ExpectType boolean +} + +// The compiler throws an error if the function is provided a first argument which is not a collection... +{ + isSortedAscending( 5 ); // $ExpectError + isSortedAscending( true ); // $ExpectError + isSortedAscending( false ); // $ExpectError + isSortedAscending( null ); // $ExpectError + isSortedAscending( {} ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + isSortedAscending(); // $ExpectError + isSortedAscending( [ 1, 2, 3 ], {} ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/examples/index.js b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/examples/index.js new file mode 100644 index 000000000000..af19eb395396 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/examples/index.js @@ -0,0 +1,47 @@ +/** +* @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'; + +var AccessorArray = require( '@stdlib/array/base/accessor' ); +var isSortedAscending = require( './../lib' ); + +var x = new AccessorArray( [ 1, 2, 3, 4 ] ); +var bool = isSortedAscending( x ); +console.log( bool ); +// => true + +x = new AccessorArray( [ 1, 1, 1, 1 ] ); +bool = isSortedAscending( x ); +console.log( bool ); +// => true + +x = new AccessorArray( [ 1 ] ); +bool = isSortedAscending( x ); +console.log( bool ); +// => true + +x = new AccessorArray( [ 1, 3, 2, 4 ] ); +bool = isSortedAscending( x ); +console.log( bool ); +// => false + +x = new AccessorArray( [ 4, 3, 2, 1 ] ); +bool = isSortedAscending( x ); +console.log( bool ); +// => false diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/lib/index.js b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/lib/index.js new file mode 100644 index 000000000000..e1b44b005936 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/lib/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +/** +* Test if an array is sorted in ascending order. +* +* @module @stdlib/array/base/assert/is-sorted-ascending +* +* @example +* var isSortedAscending = require( '@stdlib/array/base/assert/is-sorted-ascending' ); +* +* var out = isSortedAscending( [ 1, 2, 3 ] ); +* // returns true +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/lib/main.js b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/lib/main.js new file mode 100644 index 000000000000..af37cfde0b79 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/lib/main.js @@ -0,0 +1,100 @@ +/** +* @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 isAccessorArray = require( '@stdlib/array/base/assert/is-accessor-array' ); +var accessorGetter = require( '@stdlib/array/base/accessor-getter' ); +var getter = require( '@stdlib/array/base/getter' ); +var dtype = require( '@stdlib/array/dtype' ); + + +// MAIN // + +/** +* Tests if an array is sorted in ascending order. +* +* @param {Collection} x - input array +* @returns {boolean} boolean indicating if an array is sorted in ascending order +* +* @example +* var out = isSortedAscending( [ 1, 2, 3 ] ); +* // returns true +* +* @example +* var out = isSortedAscending( [ 3, 2, 1 ] ); +* // returns false +* +* @example +* var out = isSortedAscending( [ 3, 3, 3 ] ); +* // returns true +* +* @example +* var out = isSortedAscending( [ 3 ] ); +* // returns true +* +* @example +* var out = isSortedAscending( [] ); +* // returns false +* +* @example +* var out = isSortedAscending( [ 1, 3, 2 ] ); +* // returns false +*/ +function isSortedAscending( x ) { + var len; + var get; + var dt; + var v1; + var v2; + var i; + + // Resolve the input array data type: + dt = dtype( x ); + + // Resolve an accessor for retrieving input array elements: + if ( isAccessorArray( x ) ) { + get = accessorGetter( dt ); + } else { + get = getter( dt ); + } + // Get the number of elements over which to iterate: + len = x.length; + + // Check for an empty array: + if ( len === 0 ) { + return false; + } + // Loop over the elements... + v1 = get( x, 0 ); + for ( i = 1; i < len; i++ ) { + v2 = get( x, i ); + if ( v1 > v2 ) { + return false; + } + v1 = v2; + } + return true; +} + + +// EXPORTS // + +module.exports = isSortedAscending; diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/package.json b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/package.json new file mode 100644 index 000000000000..7fe5f635babb --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/package.json @@ -0,0 +1,64 @@ +{ + "name": "@stdlib/array/base/assert/is-sorted-ascending", + "version": "0.0.0", + "description": "Test if an array is sorted in ascending order.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdtypes", + "types", + "data", + "structure", + "array", + "generic", + "sorted", + "ascending", + "ordered", + "assert" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/test/test.js b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/test/test.js new file mode 100644 index 000000000000..5aca2515c895 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/assert/is-sorted-ascending/test/test.js @@ -0,0 +1,96 @@ +/** +* @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 tape = require( 'tape' ); +var AccessorArray = require( '@stdlib/array/base/accessor' ); +var isSortedAscending = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof isSortedAscending, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function tests whether an array is sorted in ascending order', function test( t ) { + var actual; + var x; + + x = [ 1, 2, 3 ]; + actual = isSortedAscending( x ); + t.strictEqual( actual, true, 'returns expected value' ); + + x = [ 1, 1, 1 ]; + actual = isSortedAscending( x ); + t.strictEqual( actual, true, 'returns expected value' ); + + x = [ 1 ]; + actual = isSortedAscending( x ); + t.strictEqual( actual, true, 'returns expected value' ); + + x = [ 3, 2, 1 ]; + actual = isSortedAscending( x ); + t.strictEqual( actual, false, 'returns expected value' ); + + x = []; + actual = isSortedAscending( x ); + t.strictEqual( actual, false, 'returns expected value' ); + + x = [ 2, 1, 3 ]; + actual = isSortedAscending( x ); + t.strictEqual( actual, false, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function tests whether an array is sorted in ascending order (accessors)', function test( t ) { + var actual; + var x; + + x = new AccessorArray( [ 1, 2, 3 ] ); + actual = isSortedAscending( x ); + t.strictEqual( actual, true, 'returns expected value' ); + + x = new AccessorArray( [ 1, 1, 1 ] ); + actual = isSortedAscending( x ); + t.strictEqual( actual, true, 'returns expected value' ); + + x = new AccessorArray( [ 1 ] ); + actual = isSortedAscending( x ); + t.strictEqual( actual, true, 'returns expected value' ); + + x = new AccessorArray( [ 3, 2, 1 ] ); + actual = isSortedAscending( x ); + t.strictEqual( actual, false, 'returns expected value' ); + + x = new AccessorArray( [] ); + actual = isSortedAscending( x ); + t.strictEqual( actual, false, 'returns expected value' ); + + x = new AccessorArray( [ 2, 1, 3 ] ); + actual = isSortedAscending( x ); + t.strictEqual( actual, false, 'returns expected value' ); + + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/assert/lib/index.js b/lib/node_modules/@stdlib/array/base/assert/lib/index.js index 149c00d7cb19..cde6bf937a63 100644 --- a/lib/node_modules/@stdlib/array/base/assert/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/assert/lib/index.js @@ -234,6 +234,15 @@ setReadOnly( ns, 'isSameKindDataTypeCast', require( '@stdlib/array/base/assert/i */ setReadOnly( ns, 'isSignedIntegerDataType', require( '@stdlib/array/base/assert/is-signed-integer-data-type' ) ); +/** +* @name isSortedAscending +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/assert/is-sorted-ascending} +*/ +setReadOnly( ns, 'isSortedAscending', require( '@stdlib/array/base/assert/is-sorted-ascending' ) ); + /** * @name isUnsignedIntegerDataType * @memberof ns diff --git a/lib/node_modules/@stdlib/array/base/cuevery-by-right/README.md b/lib/node_modules/@stdlib/array/base/cuevery-by-right/README.md index 17dca3bf05b6..d0a0268f9ce3 100644 --- a/lib/node_modules/@stdlib/array/base/cuevery-by-right/README.md +++ b/lib/node_modules/@stdlib/array/base/cuevery-by-right/README.md @@ -66,9 +66,9 @@ var bool = ( out === y ); The invoked `predicate` function is provided three arguments: -- **value**: collection element, -- **index**: collection index, -- **collection**: input collection, +- **value**: collection element. +- **index**: collection index. +- **collection**: input collection. To set the function execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/base/cuevery-by/lib/assign.js b/lib/node_modules/@stdlib/array/base/cuevery-by/lib/assign.js index 365ef9412513..49f64922c962 100644 --- a/lib/node_modules/@stdlib/array/base/cuevery-by/lib/assign.js +++ b/lib/node_modules/@stdlib/array/base/cuevery-by/lib/assign.js @@ -146,7 +146,7 @@ function accessors( x, out, stride, offset, predicate, thisArg ) { * * @example * function isPositive( value ) { -* return ( value > 0 ); +* return ( value > 0 ); * } * * var x = [ 1, 1, 1, 0, 1 ]; diff --git a/lib/node_modules/@stdlib/array/base/cunone-by-right/lib/assign.js b/lib/node_modules/@stdlib/array/base/cunone-by-right/lib/assign.js index 12cf3a4cf878..8614414ccc7f 100644 --- a/lib/node_modules/@stdlib/array/base/cunone-by-right/lib/assign.js +++ b/lib/node_modules/@stdlib/array/base/cunone-by-right/lib/assign.js @@ -136,7 +136,7 @@ function accessors( x, out, stride, offset, predicate, thisArg ) { * * @example * function fcn( value ) { -* return ( value > 0 ); +* return ( value > 0 ); * } * * var x = [ 1, 1, 0, 0 ]; diff --git a/lib/node_modules/@stdlib/array/base/cusome-by-right/lib/index.js b/lib/node_modules/@stdlib/array/base/cusome-by-right/lib/index.js index 7d0e5b424cbe..e6fb3441cbb7 100644 --- a/lib/node_modules/@stdlib/array/base/cusome-by-right/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/cusome-by-right/lib/index.js @@ -39,7 +39,7 @@ * var cusomeByRight = require( '@stdlib/array/base/cusome-by-right' ); * * function fcn( value ) { -* return ( value > 0 ); +* return ( value > 0 ); * } * * var x = [ 1, 1, 0, 0, 0 ]; diff --git a/lib/node_modules/@stdlib/array/base/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/docs/types/index.d.ts index 5008dcd1a3cf..512946c21756 100644 --- a/lib/node_modules/@stdlib/array/base/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/docs/types/index.d.ts @@ -52,8 +52,15 @@ import bbinary3d = require( '@stdlib/array/base/broadcasted-binary3d' ); import bbinary4d = require( '@stdlib/array/base/broadcasted-binary4d' ); import bbinary5d = require( '@stdlib/array/base/broadcasted-binary5d' ); import bquaternary2d = require( '@stdlib/array/base/broadcasted-quaternary2d' ); +import bquaternary3d = require( '@stdlib/array/base/broadcasted-quaternary3d' ); +import bquaternary4d = require( '@stdlib/array/base/broadcasted-quaternary4d' ); +import bquaternary5d = require( '@stdlib/array/base/broadcasted-quaternary5d' ); import bquinary2d = require( '@stdlib/array/base/broadcasted-quinary2d' ); +import bquinary4d = require( '@stdlib/array/base/broadcasted-quinary4d' ); import bternary2d = require( '@stdlib/array/base/broadcasted-ternary2d' ); +import bternary3d = require( '@stdlib/array/base/broadcasted-ternary3d' ); +import bternary4d = require( '@stdlib/array/base/broadcasted-ternary4d' ); +import bternary5d = require( '@stdlib/array/base/broadcasted-ternary5d' ); import bunary2d = require( '@stdlib/array/base/broadcasted-unary2d' ); import bunary3d = require( '@stdlib/array/base/broadcasted-unary3d' ); import bunary4d = require( '@stdlib/array/base/broadcasted-unary4d' ); @@ -77,6 +84,7 @@ import everyBy = require( '@stdlib/array/base/every-by' ); import everyByRight = require( '@stdlib/array/base/every-by-right' ); import fancySlice = require( '@stdlib/array/base/fancy-slice' ); import fancySliceAssign = require( '@stdlib/array/base/fancy-slice-assign' ); +import fill = require( '@stdlib/array/base/fill' ); import filled = require( '@stdlib/array/base/filled' ); import filledBy = require( '@stdlib/array/base/filled-by' ); import filled2d = require( '@stdlib/array/base/filled2d' ); @@ -119,6 +127,7 @@ import groupValues = require( '@stdlib/array/base/group-values' ); import groupValuesBy = require( '@stdlib/array/base/group-values-by' ); import incrspace = require( '@stdlib/array/base/incrspace' ); import indexOf = require( '@stdlib/array/base/index-of' ); +import indicesComplement = require( '@stdlib/array/base/indices-complement' ); import join = require( '@stdlib/array/base/join' ); import last = require( '@stdlib/array/base/last' ); import lastIndexOf = require( '@stdlib/array/base/last-index-of' ); @@ -131,11 +140,19 @@ import map5d = require( '@stdlib/array/base/map5d' ); import minSignedIntegerDataType = require( '@stdlib/array/base/min-signed-integer-dtype' ); import minUnsignedIntegerDataType = require( '@stdlib/array/base/min-unsigned-integer-dtype' ); import mskbinary2d = require( '@stdlib/array/base/mskbinary2d' ); +import mskbinary3d = require( '@stdlib/array/base/mskbinary3d' ); +import mskbinary4d = require( '@stdlib/array/base/mskbinary4d' ); +import mskbinary5d = require( '@stdlib/array/base/mskbinary5d' ); import mskfilter = require( '@stdlib/array/base/mskfilter' ); +import mskfilterMap = require( '@stdlib/array/base/mskfilter-map' ); +import mskfilter2 = require( '@stdlib/array/base/mskfilter2' ); +import mskfiltern = require( '@stdlib/array/base/mskfiltern' ); import mskput = require( '@stdlib/array/base/mskput' ); import mskreject = require( '@stdlib/array/base/mskreject' ); import mskunary2d = require( '@stdlib/array/base/mskunary2d' ); import mskunary3d = require( '@stdlib/array/base/mskunary3d' ); +import mskunary4d = require( '@stdlib/array/base/mskunary4d' ); +import mskunary5d = require( '@stdlib/array/base/mskunary5d' ); import nCartesianProduct = require( '@stdlib/array/base/n-cartesian-product' ); import none = require( '@stdlib/array/base/none' ); import noneBy = require( '@stdlib/array/base/none-by' ); @@ -163,6 +180,8 @@ import removeAt = require( '@stdlib/array/base/remove-at' ); import resolveGetter = require( '@stdlib/array/base/resolve-getter' ); import resolveSetter = require( '@stdlib/array/base/resolve-setter' ); import reverse = require( '@stdlib/array/base/reverse' ); +import scatterFilled = require( '@stdlib/array/base/scatter-filled' ); +import scattered = require( '@stdlib/array/base/scattered' ); import setter = require( '@stdlib/array/base/setter' ); import slice = require( '@stdlib/array/base/slice' ); import strided2array2d = require( '@stdlib/array/base/strided2array2d' ); @@ -171,6 +190,7 @@ import strided2array4d = require( '@stdlib/array/base/strided2array4d' ); import strided2array5d = require( '@stdlib/array/base/strided2array5d' ); import take = require( '@stdlib/array/base/take' ); import takeIndexed = require( '@stdlib/array/base/take-indexed' ); +import takeIndexed2 = require( '@stdlib/array/base/take-indexed2' ); import take2d = require( '@stdlib/array/base/take2d' ); import take3d = require( '@stdlib/array/base/take3d' ); import ternary2d = require( '@stdlib/array/base/ternary2d' ); @@ -183,8 +203,11 @@ import toReversed = require( '@stdlib/array/base/to-reversed' ); import unary2d = require( '@stdlib/array/base/unary2d' ); import unary2dBy = require( '@stdlib/array/base/unary2d-by' ); import unary3d = require( '@stdlib/array/base/unary3d' ); +import unary3dBy = require( '@stdlib/array/base/unary3d-by' ); import unary4d = require( '@stdlib/array/base/unary4d' ); +import unary4dBy = require( '@stdlib/array/base/unary4d-by' ); import unary5d = require( '@stdlib/array/base/unary5d' ); +import unary5dBy = require( '@stdlib/array/base/unary5d-by' ); import unarynd = require( '@stdlib/array/base/unarynd' ); import unitspace = require( '@stdlib/array/base/unitspace' ); import where = require( '@stdlib/array/base/where' ); @@ -1042,6 +1065,117 @@ interface Namespace { */ bquaternary2d: typeof bquaternary2d; + /** + * Applies a quaternary callback to elements in four broadcasted input arrays and assigns results to elements in a three-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing four input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - quaternary callback + * + * @example + * var add = require( '@stdlib/math/base/ops/add4' ); + * var ones3d = require( '@stdlib/array/base/ones3d' ); + * var zeros3d = require( '@stdlib/array/base/zeros3d' ); + * + * var shapes = [ + * [ 1, 1, 3 ], + * [ 3, 1, 1 ], + * [ 1, 3, 1 ], + * [ 3, 3, 3 ], + * [ 3, 3, 3 ] + * ]; + * + * var x = ones3d( shapes[ 0 ] ); + * var y = ones3d( shapes[ 1 ] ); + * var z = ones3d( shapes[ 2 ] ); + * var w = ones3d( shapes[ 3 ] ); + * var out = zeros3d( shapes[ 4 ] ); + * + * ns.bquaternary3d( [ x, y, z, w, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ], [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ], [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ] ] + */ + bquaternary3d: typeof bquaternary3d; + + /** + * Applies a quaternary callback to elements in four broadcasted input arrays and assigns results to elements in a four-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing four input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - quaternary callback + * + * @example + * var add = require( '@stdlib/math/base/ops/add4' ); + * var ones4d = require( '@stdlib/array/base/ones4d' ); + * var zeros4d = require( '@stdlib/array/base/zeros4d' ); + * + * var shapes = [ + * [ 1, 3, 1, 1 ], + * [ 1, 1, 3, 1 ], + * [ 1, 1, 1, 3 ], + * [ 1, 1, 1, 1 ], + * [ 1, 3, 3, 3 ] + * ]; + * + * var x = ones4d( shapes[ 0 ] ); + * var y = ones4d( shapes[ 1 ] ); + * var z = ones4d( shapes[ 2 ] ); + * var w = ones4d( shapes[ 3 ] ); + * var out = zeros4d( shapes[ 4 ] ); + * + * ns.bquaternary4d( [ x, y, z, w, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ], [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ], [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ] ] ] + */ + bquaternary4d: typeof bquaternary4d; + + /** + * Applies a quaternary callback to elements in four broadcasted input arrays and assigns results to elements in a five-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing four input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - quaternary callback + * + * @example + * var add = require( '@stdlib/math/base/ops/add4' ); + * var ones5d = require( '@stdlib/array/base/ones5d' ); + * var zeros5d = require( '@stdlib/array/base/zeros5d' ); + * + * var shapes = [ + * [ 1, 1, 3, 1, 1 ], + * [ 1, 1, 1, 3, 1 ], + * [ 1, 1, 1, 1, 3 ], + * [ 1, 1, 1, 1, 1 ], + * [ 1, 1, 3, 3, 3 ] + * ]; + * + * var x = ones5d( shapes[ 0 ] ); + * var y = ones5d( shapes[ 1 ] ); + * var z = ones5d( shapes[ 2 ] ); + * var w = ones5d( shapes[ 3 ] ); + * var out = zeros5d( shapes[ 4 ] ); + * + * ns.bquaternary5d( [ x, y, z, w, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ], [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ], [ [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ], [ 4.0, 4.0, 4.0 ] ] ] ] ] + */ + bquaternary5d: typeof bquaternary5d; + /** * Applies a quinary callback to elements in five broadcasted input arrays and assigns results to elements in a two-dimensional nested output array. * @@ -1084,6 +1218,48 @@ interface Namespace { */ bquinary2d: typeof bquinary2d; + /** + * Applies a quinary callback to elements in five broadcasted input arrays and assigns results to elements in a four-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing five input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - quinary callback + * + * @example + * var ones4d = require( '@stdlib/array/base/ones4d' ); + * var zeros4d = require( '@stdlib/array/base/zeros4d' ); + * + * function add( x, y, z, w, v ) { + * return x + y + z + w + v; + * } + * + * var shapes = [ + * [ 1, 1, 1, 2 ], + * [ 1, 1, 2, 1 ], + * [ 1, 1, 2, 2 ], + * [ 1, 2, 1, 1 ], + * [ 2, 2, 2, 2 ], + * [ 2, 2, 2, 2 ] + * ]; + * + * var x = ones4d( shapes[ 0 ] ); + * var y = ones4d( shapes[ 1 ] ); + * var z = ones4d( shapes[ 2 ] ); + * var w = ones4d( shapes[ 3 ] ); + * var v = ones4d( shapes[ 4 ] ); + * var out = zeros4d( shapes[ 5 ] ); + * + * ns.bquinary4d( [ x, y, z, w, v, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ [ 5.0, 5.0 ], [ 5.0, 5.0 ] ], [ [ 5.0, 5.0 ], [ 5.0, 5.0 ] ] ], [ [ [ 5.0, 5.0 ], [ 5.0, 5.0 ] ], [ [ 5.0, 5.0 ], [ 5.0, 5.0 ] ] ] ] + */ + bquinary4d: typeof bquinary4d; + /** * Applies a ternary callback to elements in three broadcasted input arrays and assigns results to elements in a two-dimensional nested output array. * @@ -1119,6 +1295,111 @@ interface Namespace { */ bternary2d: typeof bternary2d; + /** + * Applies a ternary callback to elements in three broadcasted input arrays and assigns results to elements in a three-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing three input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - ternary callback + * + * @example + * var ones3d = require( '@stdlib/array/base/ones3d' ); + * var zeros3d = require( '@stdlib/array/base/zeros3d' ); + * var add = require( '@stdlib/math/base/ops/add3' ); + * + * var shapes = [ + * [ 1, 2, 1 ], + * [ 2, 1, 1 ], + * [ 1, 1, 2 ], + * [ 2, 2, 2 ] + * ]; + * + * var x = ones3d( shapes[ 0 ] ); + * var y = ones3d( shapes[ 1 ] ); + * var z = ones3d( shapes[ 2 ] ); + * var out = zeros3d( shapes[ 3 ] ); + * + * ns.bternary3d( [ x, y, z, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ 3.0, 3.0 ], [ 3.0, 3.0 ] ], [ [ 3.0, 3.0 ], [ 3.0, 3.0 ] ] ] + */ + bternary3d: typeof bternary3d; + + /** + * Applies a ternary callback to elements in three broadcasted input arrays and assigns results to elements in a four-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing three input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - ternary callback + * + * @example + * var ones4d = require( '@stdlib/array/base/ones4d' ); + * var zeros4d = require( '@stdlib/array/base/zeros4d' ); + * var add = require( '@stdlib/math/base/ops/add3' ); + * + * var shapes = [ + * [ 1, 2, 1, 1 ], + * [ 2, 1, 1, 1 ], + * [ 1, 1, 2, 1 ], + * [ 2, 2, 2, 2 ] + * ]; + * + * var x = ones4d( shapes[ 0 ] ); + * var y = ones4d( shapes[ 1 ] ); + * var z = ones4d( shapes[ 2 ] ); + * var out = zeros4d( shapes[ 3 ] ); + * + * ns.bternary4d( [ x, y, z, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ 3.0, 3.0 ], [ 3.0, 3.0 ] ], [ [ 3.0, 3.0 ], [ 3.0, 3.0 ] ], [ [ 3.0, 3.0 ], [ 3.0, 3.0 ] ], [ [ 3.0, 3.0 ], [ 3.0, 3.0 ] ] ] + */ + bternary4d: typeof bternary4d; + + /** + * Applies a ternary callback to elements in three broadcasted input arrays and assigns results to elements in a five-dimensional nested output array. + * + * ## Notes + * + * - The input array shapes must be broadcast compatible with the output array shape. + * + * @param arrays - array containing three input nested arrays and one output nested array + * @param shapes - array shapes + * @param fcn - ternary callback + * + * @example + * var ones5d = require( '@stdlib/array/base/ones5d' ); + * var zeros5d = require( '@stdlib/array/base/zeros5d' ); + * var add = require( '@stdlib/math/base/ops/add3' ); + * var ns.bternary5d = require( '@stdlib/array/base/broadcasted-ternary5d' ); + * var shapes = [ + * [ 1, 2, 1, 1, 1 ], + * [ 2, 1, 1, 1, 1 ], + * [ 1, 1, 1, 1, 1 ], + * [ 2, 2, 1, 1, 1 ] + * ]; + * + * var x = ones5d( shapes[ 0 ] ); + * var y = ones5d( shapes[ 1 ] ); + * var z = ones5d( shapes[ 2 ] ); + * var out = zeros5d( shapes[ 3 ] ); + * + * ns.bternary5d( [ x, y, z, out ], shapes, add ); + * + * console.log( out ); + * // => [ [ [ [ [ 3 ] ] ], [ [ [ 3 ] ] ] ], [ [ [ 3 ] ] ], [ [ [ 3 ] ] ] ] ] + */ + bternary5d: typeof bternary5d; + /** * Applies a unary callback to elements in a broadcasted nested input array and assigns results to elements in a two-dimensional nested output array. * @@ -1643,6 +1924,29 @@ interface Namespace { */ fancySliceAssign: typeof fancySliceAssign; + /** + * Fills all elements within a portion of an array with a specified value. + * + * @param x - input array + * @param value - fill value + * @param start - starting index (inclusive) + * @param end - ending index (exclusive) + * @returns modified input array + * + * @example + * var x = [ 1, 2, 3 ]; + * + * var out = ns.fill( x, 4, 0, 3 ); + * // returns [ 4, 4, 4 ] + * + * @example + * var x = [ 1, 2, 3, 4, 5, 6 ]; + * + * var out = ns.fill( x, 8, 0, 3 ); + * // returns [ 8, 8, 8, 4, 5, 6 ] + */ + fill: typeof fill; + /** * Returns a filled "generic" array. * @@ -2513,6 +2817,19 @@ interface Namespace { */ indexOf: typeof indexOf; + /** + * Returns the complement of a list of array indices. + * + * @param N - array length + * @param indices - list of indices + * @returns indices complement + * + * @example + * var idx = ns.indicesComplement( 5, [ 1, 3 ] ); + * // returns [ 0, 2, 4 ] + */ + indicesComplement: typeof indicesComplement; + /** * Returns a string created by joining array elements using a specified separator. * @@ -2888,54 +3205,226 @@ interface Namespace { mskbinary2d: typeof mskbinary2d; /** - * Returns a new array by applying a mask to a provided input array. - * - * @param x - input array - * @param mask - mask array - * @returns output array + * Applies a binary callback to elements in two three-dimensional nested input arrays according to elements in a three-dimensional nested mask array and assigns results to elements in a three-dimensional nested output array. * - * @example - * var x = [ 1, 2, 3, 4 ]; + * ## Notes * - * var y = ns.mskfilter( x, [ 0, 1, 0, 1 ] ); - * // returns [ 2, 4 ] - */ - mskfilter: typeof mskfilter; - - /** - * Replaces elements of an array with provided values according to a provided mask array. + * - The function assumes that the input and output arrays have the same shape. + * - An element in an input array is "masked" if the corresponding element in the mask array is non-zero. * - * @param x - input array - * @param mask - mask array - * @param values - values to set - * @param mode - string specifying behavior when the number of values does not equal the number of falsy values in the mask array - * @returns input array + * @param arrays - array containing two input nested arrays, an input nested mask array, and one output nested array + * @param shape - array shape + * @param fcn - binary callback * * @example - * var x = [ 1, 2, 3, 4 ]; - * - * var mask = [ 1, 0, 0, 1 ]; - * var values = [ 20, 30 ]; + * var ones3d = require( '@stdlib/array/base/ones3d' ); + * var zeros3d = require( '@stdlib/array/base/zeros3d' ); + * var add = require( '@stdlib/math/base/ops/add' ); * - * var out = ns.mskput( x, mask, values, 'strict' ); - * // returns [ 1, 20, 30, 4 ] + * var shape = [ 2, 2, 2 ]; * - * var bool = ( out === x ); - * // returns true + * var x = ones3d( shape ); + * var y = ones3d( shape ); + * var z = zeros3d( shape ); * - * @example - * var x = [ 1, 2, 3, 4 ]; + * var mask = [ + * [ [ 0, 1 ], [ 0, 0 ] ], + * [ [ 1, 0 ], [ 0, 1 ] ] + * ]; * - * var out = ns.mskput( x, [ 1, 0, 0, 1 ], [ 30 ], 'strict_broadcast' ); - * // returns [ 1, 30, 30, 4 ] + * ns.mskbinary3d( [ x, y, mask, z ], shape, add ); * - * var bool = ( out === x ); - * // returns true + * console.log( z ); + * // => [ [ [ 2.0, 0.0 ], [ 2.0, 2.0 ] ], [ [ 0.0, 2.0 ], [ 2.0, 0.0 ] ] ] */ - mskput: typeof mskput; + mskbinary3d: typeof mskbinary3d; /** - * Returns a new array by applying a mask to a provided input array. + * Applies a binary callback to elements in two four-dimensional nested input arrays according to elements in a four-dimensional nested mask array and assigns results to elements in a four-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * - An element in an input array is "masked" if the corresponding element in the mask array is non-zero. + * + * @param arrays - array containing two input nested arrays, an input nested mask array, and one output nested array + * @param shape - array shape + * @param fcn - binary callback + * + * @example + * var ones4d = require( '@stdlib/array/base/ones4d' ); + * var zeros4d = require( '@stdlib/array/base/zeros4d' ); + * var add = require( '@stdlib/math/base/ops/add' ); + * + * var shape = [ 1, 1, 2, 2 ]; + * + * var x = ones4d( shape ); + * var y = ones4d( shape ); + * var z = zeros4d( shape ); + * + * var mask = [ [ [ [ 0, 1 ], [ 0, 0 ] ] ] ]; + * + * mskbinary2d( [ x, y, mask, z ], shape, add ); + * + * console.log( z ); + * // => [ [ [ [ 2.0, 0.0 ], [ 2.0, 2.0 ] ] ] ] + */ + mskbinary4d: typeof mskbinary4d; + + /** + * Applies a binary callback to elements in two five-dimensional nested input arrays according to elements in a five-dimensional nested mask array and assigns results to elements in a five-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * - An element in an input array is "masked" if the corresponding element in the mask array is non-zero. + * + * @param arrays - array containing two input nested arrays, an input nested mask array, and one output nested array + * @param shape - array shape + * @param fcn - binary callback + * + * @example + * var ones5d = require( '@stdlib/array/base/ones5d' ); + * var zeros5d = require( '@stdlib/array/base/zeros5d' ); + * var add = require( '@stdlib/math/base/ops/add' ); + * + * var shape = [ 1, 1, 1, 2, 2 ]; + * + * var x = ones5d( shape ); + * var y = ones5d( shape ); + * var z = zeros5d( shape ); + * + * var mask = [ [ [ [ [ 0, 1 ], [ 0, 0 ] ] ] ] ]; + * + * ns.mskbinary5d( [ x, y, mask, z ], shape, add ); + * + * console.log( z ); + * // => [ [ [ [ [ 2.0, 0.0 ], [ 2.0, 2.0 ] ] ] ] ] + */ + mskbinary5d: typeof mskbinary5d; + + /** + * Returns a new array by applying a mask to a provided input array. + * + * @param x - input array + * @param mask - mask array + * @returns output array + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * + * var y = ns.mskfilter( x, [ 0, 1, 0, 1 ] ); + * // returns [ 2, 4 ] + */ + mskfilter: typeof mskfilter; + + /** + * Returns a new array after applying a mask and a callback function to a provided input array. + * + * @param x - input array + * @param mask - mask array + * @param clbk - callback function + * @param thisArg - callback execution context + * @returns output array + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * + * function scale( val ) { + * return 10 * val; + * } + * + * var y = ns.mskfilterMap( x, [ 0, 1, 0, 1 ], scale ); + * // returns [ 20, 40 ] + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * var mask = [ 0, 1, 0, 1 ]; + * + * var out = [ 0, 0, 0, 0 ]; + * + * function scale( x ) { + * return x * 10; + * } + * + * var arr = ns.mskfilterMap.assign( x, mask, out, 1, 0, scale ); + * // returns [ 20, 40, 0, 0 ] + * + * var bool = ( arr === out ); + * // returns true + */ + mskfilterMap: typeof mskfilterMap; + + /** + * Returns new arrays by applying a mask to two provided input arrays in a single pass. + * + * @param x - first input array + * @param y - second input array + * @param mask - mask array + * @returns output arrays + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * var y = [ 5, 6, 7, 8 ]; + * var mask = [ 0, 1, 0, 1 ]; + * + * var out = ns.mskfilter2( x, y, mask ); + * // returns [ [ 2, 4 ], [ 6, 8 ] ] + */ + mskfilter2: typeof mskfilter2; + + /** + * Returns new arrays by applying a mask to one or more provided input arrays in a single pass. + * + * @param x - first input array + * @param y - second input array (or mask) + * @param arrays - additional input arrays and mask + * @returns output arrays + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * var y = [ 5, 6, 7, 8 ]; + * var mask = [ 0, 1, 0, 1 ]; + * + * var out = ns.mskfiltern( x, y, mask ); + * // returns [ [ 2, 4 ], [ 6, 8 ] ] + */ + mskfiltern: typeof mskfiltern; + + /** + * Replaces elements of an array with provided values according to a provided mask array. + * + * @param x - input array + * @param mask - mask array + * @param values - values to set + * @param mode - string specifying behavior when the number of values does not equal the number of falsy values in the mask array + * @returns input array + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * + * var mask = [ 1, 0, 0, 1 ]; + * var values = [ 20, 30 ]; + * + * var out = ns.mskput( x, mask, values, 'strict' ); + * // returns [ 1, 20, 30, 4 ] + * + * var bool = ( out === x ); + * // returns true + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * + * var out = ns.mskput( x, [ 1, 0, 0, 1 ], [ 30 ], 'strict_broadcast' ); + * // returns [ 1, 30, 30, 4 ] + * + * var bool = ( out === x ); + * // returns true + */ + mskput: typeof mskput; + + /** + * Returns a new array by applying a mask to a provided input array. * * @param x - input array * @param mask - mask array @@ -3017,6 +3506,74 @@ interface Namespace { */ mskunary3d: typeof mskunary3d; + /** + * Applies a unary callback to elements in a four-dimensional nested input array according to elements in a four-dimensional nested mask array and assigns results to elements in a four-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * - An element in an input array is "masked" if the corresponding element in the mask array is non-zero. + * + * @param arrays - array containing one input nested array, an input nested mask array, and one output nested array + * @param shape - array shape + * @param fcn - unary callback + * + * @example + * var ones4d = require( '@stdlib/array/base/ones4d' ); + * var zeros4d = require( '@stdlib/array/base/zeros4d' ); + * + * function scale( x ) { + * return x * 10.0; + * } + * + * var shape = [ 1, 1, 2, 2 ]; + * + * var x = ones4d( shape ); + * var y = zeros4d( shape ); + * + * var mask = [ [ [ [ 0, 1 ], [ 0, 0 ] ] ] ]; + * + * ns.mskunary4d( [ x, mask, y ], shape, scale ); + * + * console.log( y ); + * // => [ [ [ [ 10.0, 0.0 ], [ 10.0, 10.0 ] ] ] ] + */ + mskunary4d: typeof mskunary4d; + + /** + * Applies a unary callback to elements in a five-dimensional nested input array according to elements in a five-dimensional nested mask array and assigns results to elements in a five-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * - An element in an input array is "masked" if the corresponding element in the mask array is non-zero. + * + * @param arrays - array containing one input nested array, an input nested mask array, and one output nested array + * @param shape - array shape + * @param fcn - unary callback + * + * @example + * var ones5d = require( '@stdlib/array/base/ones5d' ); + * var zeros5d = require( '@stdlib/array/base/zeros5d' ); + * + * function scale( x ) { + * return x * 10.0; + * } + * + * var shape = [ 1, 1, 1, 2, 2 ]; + * + * var x = ones5d( shape ); + * var y = zeros5d( shape ); + * + * var mask = [ [ [ [ [ 0, 1 ], [ 0, 0 ] ] ] ] ]; + * + * ns.mskunary5d( [ x, mask, y ], shape, scale ); + * + * console.log( y ); + * // => [ [ [ [ [ 10.0, 0.0 ], [ 10.0, 10.0 ] ] ] ] ] + */ + mskunary5d: typeof mskunary5d; + /** * Returns the n-fold Cartesian product. * @@ -3618,6 +4175,51 @@ interface Namespace { */ reverse: typeof reverse; + /** + * Scatters a list of provided values to specified indices in a new filled "generic" array. + * + * @param fill - fill value + * @param len - output array length + * @param indices - list of element indices + * @param values - values to scatter + * @param mode - index mode + * @returns output array + * + * @example + * var indices = [ 1, 2 ]; + * var values = [ 20, 30 ]; + * + * var out = ns.scatterFilled( null, 4, indices, values, 'throw' ); + * // returns [ null, 20, 30, null ] + * + * @example + * var out = ns.scatterFilled( null, 4, [ 1, 2 ], [ 30 ], 'throw' ); + * // returns [ null, 30, 30, null ] + */ + scatterFilled: typeof scatterFilled; + + /** + * Scatters a list of provided values to specified indices in a new zero-filled "generic" array. + * + * @param len - output array length + * @param indices - list of element indices + * @param values - values to scatter + * @param mode - index mode + * @returns output array + * + * @example + * var indices = [ 1, 2 ]; + * var values = [ 20, 30 ]; + * + * var out = ns.scattered( 4, indices, values, 'throw' ); + * // returns [ 0, 20, 30, 0 ] + * + * @example + * var out = ns.scattered( 4, [ 1, 2 ], [ 30 ], 'throw' ); + * // returns [ 0, 30, 30, 0 ] + */ + scattered: typeof scattered; + /** * Returns an accessor function for setting an element in an indexed array-like object. * @@ -3794,7 +4396,7 @@ interface Namespace { take: typeof take; /** - * Takes element from an indexed array. + * Takes elements from an indexed array. * * ## Notes * @@ -3812,6 +4414,28 @@ interface Namespace { */ takeIndexed: typeof takeIndexed; + /** + * Takes elements from two indexed arrays in a single pass. + * + * ## Notes + * + * - The function does **not** perform bounds checking. If an index is less than zero or greater than the maximum index of `x` or `y`, the value of the corresponding element in the respective output array is undefined. + * + * @param x - first input array + * @param y - second input array + * @param indices - list of element indices + * @returns output arrays + * + * @example + * var x = [ 1, 2, 3, 4 ]; + * var y = [ 5, 6, 7, 8 ]; + * var indices = [ 3, 1, 2, 0 ]; + * + * var out = ns.takeIndexed2( x, y, indices ); + * // returns [ [ 4, 2, 3, 1 ], [ 8, 6, 7, 5 ] ] + */ + takeIndexed2: typeof takeIndexed2; + /** * Takes elements from a two-dimensional nested array. * @@ -4153,6 +4777,43 @@ interface Namespace { */ unary3d: typeof unary3d; + /** + * Applies a unary function to each element retrieved from a three-dimensional nested input array according to a callback function and assigns results to elements in a three-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * + * @param arrays - array containing one input nested array and one output nested array + * @param shape - array shape + * @param fcn - unary function to apply to callback return values + * @param clbk - callback function + * @param thisArg - callback execution context + * + * @example + * var ones3d = require( '@stdlib/array/base/ones3d' ); + * var zeros3d = require( '@stdlib/array/base/zeros3d' ); + * + * function accessor( v ) { + * return v - 2.0; + * } + * + * function scale( x ) { + * return x * 10.0; + * } + * + * var shape = [ 1, 2, 2 ]; + * + * var x = ones3d( shape ); + * var y = zeros3d( shape ); + * + * ns.unary3dBy( [ x, y ], shape, scale ); + * + * console.log( y ); + * // => [ [ [ -10.0, -10.0 ], [ -10.0, -10.0 ] ] ] + */ + unary3dBy: typeof unary3dBy; + /** * Applies a unary callback to elements in a four-dimensional nested input array and assigns results to elements in a four-dimensional nested output array. * @@ -4184,6 +4845,43 @@ interface Namespace { */ unary4d: typeof unary4d; + /** + * Applies a unary function to each element retrieved from a four-dimensional nested input array according to a callback function and assigns results to elements in a four-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * + * @param arrays - array containing one input nested array and one output nested array + * @param shape - array shape + * @param fcn - unary function to apply to callback return values + * @param clbk - callback function + * @param thisArg - callback execution context + * + * @example + * var ones4d = require( '@stdlib/array/base/ones4d' ); + * var zeros4d = require( '@stdlib/array/base/zeros4d' ); + * + * function accessor( v ) { + * return v - 2.0; + * } + * + * function scale( x ) { + * return x * 10.0; + * } + * + * var shape = [ 1, 1, 2, 2 ]; + * + * var x = ones4d( shape ); + * var y = zeros4d( shape ); + * + * ns.unary4dBy( [ x, y ], shape, scale ); + * + * console.log( y ); + * // => [ [ [ [ -10.0, -10.0 ], [ -10.0, -10.0 ] ] ] ] + */ + unary4dBy: typeof unary4dBy; + /** * Applies a unary callback to elements in a five-dimensional nested input array and assigns results to elements in a five-dimensional nested output array. * @@ -4215,6 +4913,43 @@ interface Namespace { */ unary5d: typeof unary5d; + /** + * Applies a unary function to each element retrieved from a five-dimensional nested input array according to a callback function and assigns results to elements in a five-dimensional nested output array. + * + * ## Notes + * + * - The function assumes that the input and output arrays have the same shape. + * + * @param arrays - array containing one input nested array and one output nested array + * @param shape - array shape + * @param fcn - unary function to apply to callback return values + * @param clbk - callback function + * @param thisArg - callback execution context + * + * @example + * var ones5d = require( '@stdlib/array/base/ones5d' ); + * var zeros5d = require( '@stdlib/array/base/zeros5d' ); + * + * function accessor( v ) { + * return v - 2.0; + * } + * + * function scale( x ) { + * return x * 10.0; + * } + * + * var shape = [ 1, 1, 1, 2, 2 ]; + * + * var x = ones5d( shape ); + * var y = zeros5d( shape ); + * + * unary2dBy( [ x, y ], shape, scale ); + * + * console.log( y ); + * // => [ [ [ [ [ -10.0, -10.0 ], [ -10.0, -10.0 ] ] ] ] ] + */ + unary5dBy: typeof unary5dBy; + /** * Applies a unary callback to elements in an n-dimensional nested input array and assigns results to elements in an n-dimensional nested output array. * diff --git a/lib/node_modules/@stdlib/array/base/fill/README.md b/lib/node_modules/@stdlib/array/base/fill/README.md new file mode 100644 index 000000000000..ed7a77844aa1 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/README.md @@ -0,0 +1,136 @@ + + +# fill + +> Fill all elements within a portion of an array with a specified value. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var fill = require( '@stdlib/array/base/fill' ); +``` + +#### fill( x, value, start, end ) + +Fills all elements within a portion of an array from an inclusive `start` index to an exclusive `end` index with a specified `value`. + +```javascript +var x = [ 1, 2, 3, 4, 5, 6 ]; + +var out = fill( x, 10, 1, 4 ); +// returns [ 1, 10, 10, 10, 5, 6 ] + +var bool = ( out === x ); +// returns true +``` + +
+ + + + + +
+ +## Notes + +- If provided an array-like object having a `fill` method, the function defers execution to that method and assumes that the method API has the following signature: + + ```text + x.fill( value, start, end ) + ``` + +- If provided an array-like object without a `fill` method, the function manually sets input array elements to a provided fill value. + +- The function **mutates** the input array. + +
+ + + + + +
+ +## Examples + + + +```javascript +var Float64Array = require( '@stdlib/array/float64' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var fill = require( '@stdlib/array/base/fill' ); + +var x = new Float64Array( zeroTo( 6 ) ); +// returns [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 ] + +var y = fill( x, 10.0, 0, 6 ); +// returns [ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ] + +y = fill( x, 0.0, 0, 4 ); +// returns [ 0.0, 0.0, 0.0, 0.0, 10.0, 10.0 ] + +y = fill( x, 20.0, 2, 6 ); +// returns [ 0.0, 0.0, 20.0, 20.0, 20.0, 20.0 ] + +y = fill( x, 30.0, 2, 4 ); +// returns [ 0.0, 0.0, 30.0, 30.0, 20.0, 20.0 ] +``` + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/fill/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/fill/benchmark/benchmark.length.js new file mode 100644 index 000000000000..a13928d65ad7 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/benchmark/benchmark.length.js @@ -0,0 +1,96 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var isArray = require( '@stdlib/assert/is-array' ); +var ones = require( '@stdlib/array/base/ones' ); +var pkg = require( './../package.json' ).name; +var fill = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = ones( len ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var out; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = fill( x, i, 0, len ); + if ( out.length !== len ) { + b.fail( 'unexpected length' ); + } + } + b.toc(); + if ( !isArray( out ) ) { + b.fail( 'should return an array' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + + f = createBenchmark( len ); + bench( pkg+':dtype=generic,len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/fill/docs/repl.txt b/lib/node_modules/@stdlib/array/base/fill/docs/repl.txt new file mode 100644 index 000000000000..0ee0419524ad --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/docs/repl.txt @@ -0,0 +1,40 @@ + +{{alias}}( x, value, start, end ) + Fills all elements within a portion of an array with a specified value. + + If provided an array-like object having a `fill` method, the function + defers execution to that method and assumes that the method has the + following signature: + + x.fill( value, start, end ) + + If provided an array-like object without a `value` method, the function + manually sets input array elements to the specified value. + + Parameters + ---------- + x: ArrayLikeObject + Input array. + + value: any + Fill value. + + start: integer + Starting index (inclusive). + + end: integer + Ending index (exclusive). + + Returns + ------- + out: ArrayLikeObject + Modified input array. + + Examples + -------- + > var out = {{alias}}( [ 1, 2, 3, 4 ], 5, 1, 3 ) + [ 1, 5, 5, 4 ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/fill/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/fill/docs/types/index.d.ts new file mode 100644 index 000000000000..f9027b5d1b02 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/docs/types/index.d.ts @@ -0,0 +1,133 @@ +/* +* @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 + +/// + +import { Collection, TypedArray, ComplexTypedArray, BooleanTypedArray } from '@stdlib/types/array'; +import { ComplexLike } from '@stdlib/types/complex'; + +/** +* Fills all elements within a portion of an array with a specified value. +* +* @param x - input array +* @param value - fill value +* @param start - starting index (inclusive) +* @param end - ending index (exclusive) +* @returns modified input array +* +* @example +* var Float64Array = require( '@stdlib/array/float64' ); +* +* var x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); +* +* var out = fill( x, 4.0, 0, 3 ); +* // returns [ 4.0, 4.0, 4.0 ] +*/ +declare function fill( x: T, value: number, start: number, end: number ): T; + +/** +* Fills all elements within a portion of an array with a specified value. +* +* @param x - input array +* @param value - fill value +* @param start - starting index (inclusive) +* @param end - ending index (exclusive) +* @returns modified input array +* +* @example +* var BooleanArray = require( '@stdlib/array/bool' ); +* +* var x = new BooleanArray( [ false, false, false ] ); +* +* var out = fill( x, true, 0, 3 ); +* // returns [ true, true, true ] +*/ +declare function fill( x: T, value: boolean, start: number, end: number ): T; // eslint-disable-line @typescript-eslint/unified-signatures + +/** +* Fills all elements within a portion of an array with a specified value. +* +* @param x - input array +* @param value - fill value +* @param start - starting index (inclusive) +* @param end - ending index (exclusive) +* @returns modified input array +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var Complex128 = require( '@stdlib/complex/float64/ctor' ); +* +* var x = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* var out = fill( x, new Complex128( 7.0, 8.0 ), 0, 3 ); +* // returns [ 7.0, 8.0, 7.0, 8.0, 7.0, 8.0 ] +*/ +declare function fill( x: T, value: ComplexLike, start: number, end: number ): T; // eslint-disable-line @typescript-eslint/unified-signatures + +/** +* Fills all elements within a portion of an array with a specified value. +* +* @param x - input array +* @param value - fill value +* @param start - starting index (inclusive) +* @param end - ending index (exclusive) +* @returns modified input array +* +* @example +* var x = [ 1, 2, 3 ]; +* +* var out = fill( x, 4, 0, 3 ); +* // returns [ 4, 4, 4 ] +* +* @example +* var x = [ 1, 2, 3, 4, 5, 6 ]; +* +* var out = fill( x, 8, 0, 3 ); +* // returns [ 8, 8, 8, 4, 5, 6 ] +*/ +declare function fill( x: Array, value: U, start: number, end: number ): Array; + +/** +* Fills all elements within a portion of an array with a specified value. +* +* @param x - input array +* @param value - fill value +* @param start - starting index (inclusive) +* @param end - ending index (exclusive) +* @returns modified input array +* +* @example +* var x = [ 1, 2, 3 ]; +* +* var out = fill( x, 4, 0, 3 ); +* // returns [ 4, 4, 4 ] +* +* @example +* var x = [ 1, 2, 3, 4, 5, 6 ]; +* +* var out = fill( x, 8, 0, 3 ); +* // returns [ 8, 8, 8, 4, 5, 6 ] +*/ +declare function fill( x: Collection, value: U, start: number, end: number ): Collection; + + +// EXPORTS // + +export = fill; diff --git a/lib/node_modules/@stdlib/array/base/fill/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/fill/docs/types/test.ts new file mode 100644 index 000000000000..e2f69df9c908 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/docs/types/test.ts @@ -0,0 +1,90 @@ +/* +* @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. +*/ + +import Complex128Array = require( '@stdlib/array/complex128' ); +import Complex64Array = require( '@stdlib/array/complex64' ); +import BooleanArray = require( '@stdlib/array/bool' ); +import Complex128 = require( '@stdlib/complex/float64/ctor' ); +import fill = require( './index' ); + + +// TESTS // + +// The function returns an array... +{ + const z = new Complex128( 3.0, 5.0 ); + + fill( [ 1, 2, 3 ], 5, 0, 3 ); // $ExpectType number[] + fill( new Float64Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Float64Array + fill( new Float32Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Float32Array + fill( new Int32Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Int32Array + fill( new Int16Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Int16Array + fill( new Int8Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Int8Array + fill( new Uint32Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Uint32Array + fill( new Uint16Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Uint16Array + fill( new Uint8Array( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Uint8Array + fill( new Uint8ClampedArray( [ 1, 2, 3 ] ), 5, 0, 3 ); // $ExpectType Uint8ClampedArray + fill( new Complex128Array( [ 1, 2, 3, 4, 5, 6 ] ), z, 0, 3 ); // $ExpectType Complex128Array + fill( new Complex64Array( [ 1, 2, 3, 4, 5, 6 ] ), z, 0, 3 ); // $ExpectType Complex64Array + fill( new BooleanArray( [ true, false, true, false ] ), false, 0, 3 ); // $ExpectType BooleanArray +} + +// The compiler throws an error if the function is provided a first argument which is not a collection... +{ + fill( 5, 5, 0, 3 ); // $ExpectError + fill( true, 5, 0, 3 ); // $ExpectError + fill( false, 5, 0, 3 ); // $ExpectError + fill( null, 5, 0, 3 ); // $ExpectError + fill( void 0, 5, 0, 3 ); // $ExpectError + fill( {}, 5, 0, 3 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not a number... +{ + const x = [ 1, 2, 3 ]; + + fill( x, 5, '5', 3 ); // $ExpectError + fill( x, 5, true, 3 ); // $ExpectError + fill( x, 5, false, 3 ); // $ExpectError + fill( x, 5, null, 3 ); // $ExpectError + fill( x, 5, void 0, 3 ); // $ExpectError + fill( x, 5, {}, 3 ); // $ExpectError + fill( x, 5, ( x: number ): number => x, 3 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not a number... +{ + const x = [ 1, 2, 3 ]; + + fill( x, 0, 1, '5' ); // $ExpectError + fill( x, 0, 1, true ); // $ExpectError + fill( x, 0, 1, false ); // $ExpectError + fill( x, 0, 1, null ); // $ExpectError + fill( x, 0, 1, void 0 ); // $ExpectError + fill( x, 0, 1, {} ); // $ExpectError + fill( x, 0, 1, ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + fill(); // $ExpectError + fill( [ 1, 2, 3 ] ); // $ExpectError + fill( [ 1, 2, 3 ], 0 ); // $ExpectError + fill( [ 1, 2, 3 ], 0, 1 ); // $ExpectError + fill( [ 1, 2, 3 ], 0, 1, 3, {} ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/fill/examples/index.js b/lib/node_modules/@stdlib/array/base/fill/examples/index.js new file mode 100644 index 000000000000..9a4070f3dcc9 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/examples/index.js @@ -0,0 +1,42 @@ +/** +* @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'; + +var Float64Array = require( '@stdlib/array/float64' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var fill = require( './../lib' ); + +var x = new Float64Array( zeroTo( 6 ) ); +// returns [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0 ] + +var y = fill( x, 10.0, 0, 6 ); +console.log( y ); +// => [ 10.0, 10.0, 10.0, 10.0, 10.0, 10.0 ] + +y = fill( x, 0.0, 0, 4 ); +console.log( y ); +// => [ 0.0, 0.0, 0.0, 0.0, 10.0, 10.0 ] + +y = fill( x, 20.0, 2, 6 ); +console.log( y ); +// => [ 0.0, 0.0, 20.0, 20.0, 20.0, 20.0 ] + +y = fill( x, 30.0, 2, 4 ); +console.log( y ); +// => [ 0.0, 0.0, 30.0, 30.0, 20.0, 20.0 ] diff --git a/lib/node_modules/@stdlib/array/base/fill/lib/index.js b/lib/node_modules/@stdlib/array/base/fill/lib/index.js new file mode 100644 index 000000000000..930b285d06ea --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/lib/index.js @@ -0,0 +1,45 @@ +/** +* @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'; + +/** +* Fill all elements within a portion of an array with a specified value. +* +* @module @stdlib/array/base/fill +* +* @example +* var fill = require( '@stdlib/array/base/fill' ); +* +* var x = [ 1, 2, 3, 4 ]; +* +* var out = fill( x, 5, 1, 3 ); +* // returns [ 1, 5, 5, 4 ] +* +* var bool = ( out === x ); +* // returns true +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/fill/lib/main.js b/lib/node_modules/@stdlib/array/base/fill/lib/main.js new file mode 100644 index 000000000000..a4e5b6d6ae92 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/lib/main.js @@ -0,0 +1,164 @@ +/** +* @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 arraylike2object = require( '@stdlib/array/base/arraylike2object' ); + + +// FUNCTIONS // + +/** +* Tests whether an object has a specified method. +* +* @private +* @param {Object} obj - input object +* @param {string} method - method name +* @returns {boolean} boolean indicating whether an object has a specified method +* +* @example +* var bool = hasMethod( [], 'fill' ); +* // e.g., returns true +* +* @example +* var bool = hasMethod( [], 'beep' ); +* // returns false +*/ +function hasMethod( obj, method ) { + return ( typeof obj[ method ] === 'function' ); +} + +/** +* Fills all elements within a portion of an indexed array with a specified value. +* +* @private +* @param {Collection} x - input array +* @param {*} value - fill value +* @param {integer} start - starting index (inclusive) +* @param {integer} end - ending index (exclusive) +* @returns {Array} output array +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* +* var out = indexed( x, 5, 1, 3 ); +* // returns [ 1, 5, 5, 4 ] +*/ +function indexed( x, value, start, end ) { + var i; + for ( i = start; i < end; i++ ) { + x[ i ] = value; + } + return x; +} + +/** +* Fills all elements within a portion of an accessor array with a specified value. +* +* @private +* @param {Object} x - input array object +* @param {*} value - fill value +* @param {integer} start - starting index (inclusive) +* @param {integer} end - ending index (exclusive) +* @returns {AccessorArray} modified input array +* +* @example +* var toAccessorArray = require( '@stdlib/array/base/to-accessor-array' ); +* var arraylike2object = require( '@stdlib/array/base/arraylike2object' ); +* +* var x = toAccessorArray( [ 1, 2, 3, 4 ] ); +* var obj = arraylike2object( x ); +* +* var out = accessors( obj, 5, 1, 3 ); +* // returns +* +* var v = x.get( 0 ); +* // returns 1 +* +* v = x.get( 1 ); +* // returns 5 +* +* v = x.get( 2 ); +* // returns 5 +* +* v = x.get( 3 ); +* // returns 4 +*/ +function accessors( x, value, start, end ) { + var data; + var set; + var i; + + data = x.data; + set = x.accessors[ 1 ]; + for ( i = start; i < end; i++ ) { + set( data, i, value ); + } + return data; +} + + +// MAIN // + +/** +* Fills all elements within a portion of an array with a specified value. +* +* @param {Collection} x - input array +* @param {*} value - fill value +* @param {integer} start - starting index (inclusive) +* @param {integer} end - ending index (exclusive) +* @returns {Collection} output array +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* +* var out = fill( x, 5, 1, 3 ); +* // returns [ 1, 5, 5, 4 ] +* +* var bool = ( out === x ); +* // returns true +* +* @example +* var Int32Array = require( '@stdlib/array/int32' ); +* +* var x = new Int32Array( [ 1, 2, 3, 4 ] ); +* +* var out = fill( x, 5, 1, 3 ); +* // returns [ 1, 5, 5, 4 ] +* +* var bool = ( out === x ); +* // returns true +*/ +function fill( x, value, start, end ) { + var obj; + if ( hasMethod( x, 'fill' ) ) { + return x.fill( value, start, end ); + } + obj = arraylike2object( x ); + if ( obj.accessorProtocol ) { + return accessors( obj, value, start, end ); + } + return indexed( x, value, start, end ); +} + + +// EXPORTS // + +module.exports = fill; diff --git a/lib/node_modules/@stdlib/array/base/fill/package.json b/lib/node_modules/@stdlib/array/base/fill/package.json new file mode 100644 index 000000000000..a53b72b52154 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/package.json @@ -0,0 +1,64 @@ +{ + "name": "@stdlib/array/base/fill", + "version": "0.0.0", + "description": "Fill all elements within a portion of an array with a specified value.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdtypes", + "types", + "data", + "structure", + "array", + "generic", + "typed", + "accessor", + "fill", + "set" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/fill/test/test.js b/lib/node_modules/@stdlib/array/base/fill/test/test.js new file mode 100644 index 000000000000..8b0b021070e5 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/fill/test/test.js @@ -0,0 +1,312 @@ +/** +* @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 tape = require( 'tape' ); +var AccessorArray = require( '@stdlib/array/base/accessor' ); +var Float64Array = require( '@stdlib/array/float64' ); +var Int32Array = require( '@stdlib/array/int32' ); +var fill = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof fill, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function fills an array-like object (generic)', function test( t ) { + var expected; + var actual; + var x; + + x = [ 1, 2, 3 ]; + expected = [ 4, 4, 4 ]; + actual = fill( x, 4, 0, x.length ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = [ 1, 2, 3 ]; + expected = [ 1, 5, 5 ]; + actual = fill( x, 5, 1, x.length ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = [ 1, 2, 3 ]; + expected = [ 1, 5, 3 ]; + actual = fill( x, 5, 1, x.length-1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = [ 1, 2, 3 ]; + expected = [ 1, 2, 3 ]; + actual = fill( x, 5, 1, 1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function fills an array-like object (float64)', function test( t ) { + var expected; + var actual; + var x; + + x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + expected = new Float64Array( [ 5.0, 5.0, 5.0 ] ); + actual = fill( x, 5.0, 0, x.length ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + expected = new Float64Array( [ 1.0, 5.0, 5.0 ] ); + actual = fill( x, 5.0, 1, x.length ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + expected = new Float64Array( [ 1.0, 5.0, 3.0 ] ); + actual = fill( x, 5.0, 1, -1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + expected = new Float64Array( [ 1.0, 2.0, 3.0 ] ); + actual = fill( x, 5.0, 1, 1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function fills an array-like object (int32)', function test( t ) { + var expected; + var actual; + var x; + + x = new Int32Array( [ 1, 2, 3 ] ); + expected = new Int32Array( [ 5, 5, 5 ] ); + actual = fill( x, 5, 0, x.length ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = new Int32Array( [ 1, 2, 3 ] ); + expected = new Int32Array( [ 5, 5, 3 ] ); + actual = fill( x, 5, 0, x.length-1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = new Int32Array( [ 1, 2, 3 ] ); + expected = new Int32Array( [ 5, 2, 3 ] ); + actual = fill( x, 5, 0, x.length-2 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = new Int32Array( [ 1, 2, 3 ] ); + expected = new Int32Array( [ 1, 2, 3 ] ); + actual = fill( x, 5, 0, x.length-3 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function fills an array-like object (accessors)', function test( t ) { + var expected; + var actual; + var obj; + var x; + + x = [ 1, 2, 3, 4 ]; + expected = [ 5, 5, 5, 5 ]; + + obj = new AccessorArray( x ); + actual = fill( obj, 5, 0, x.length ); + + t.strictEqual( actual, obj, 'returns expected value' ); + t.deepEqual( x, expected, 'returns expected value' ); + + x = [ 1, 2, 3, 4 ]; + expected = [ 5, 5, 5, 4 ]; + + obj = new AccessorArray( x ); + actual = fill( obj, 5, 0, x.length-1 ); + + t.strictEqual( actual, obj, 'returns expected value' ); + t.deepEqual( x, expected, 'returns expected value' ); + + x = [ 1, 2, 3, 4 ]; + expected = [ 1, 5, 5, 4 ]; + + obj = new AccessorArray( x ); + actual = fill( obj, 5, 1, x.length-1 ); + + t.strictEqual( actual, obj, 'returns expected value' ); + t.deepEqual( x, expected, 'returns expected value' ); + + x = [ 1, 2, 3, 4 ]; + expected = [ 1, 2, 5, 4 ]; + + obj = new AccessorArray( x ); + actual = fill( obj, 5, 2, x.length-1 ); + + t.strictEqual( actual, obj, 'returns expected value' ); + t.deepEqual( x, expected, 'returns expected value' ); + + x = [ 1, 2, 3, 4 ]; + expected = [ 1, 2, 3, 4 ]; + + obj = new AccessorArray( x ); + actual = fill( obj, 5, 3, x.length-1 ); + + t.strictEqual( actual, obj, 'returns expected value' ); + t.deepEqual( x, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function fills an array-like object (array-like)', function test( t ) { + var expected; + var actual; + var x; + + x = { + 'length': 4, + '0': 1, + '1': 2, + '2': 3, + '3': 4 + }; + expected = { + 'length': 4, + '0': 5, + '1': 5, + '2': 5, + '3': 5 + }; + actual = fill( x, 5, 0, x.length ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = { + 'length': 4, + '0': 1, + '1': 2, + '2': 3, + '3': 4 + }; + expected = { + 'length': 4, + '0': 5, + '1': 5, + '2': 5, + '3': 4 + }; + actual = fill( x, 5, 0, x.length-1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = { + 'length': 4, + '0': 1, + '1': 2, + '2': 3, + '3': 4 + }; + expected = { + 'length': 4, + '0': 1, + '1': 5, + '2': 5, + '3': 4 + }; + actual = fill( x, 5, 1, x.length-1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = { + 'length': 4, + '0': 1, + '1': 2, + '2': 3, + '3': 4 + }; + expected = { + 'length': 4, + '0': 1, + '1': 2, + '2': 5, + '3': 4 + }; + actual = fill( x, 5, 2, x.length-1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + x = { + 'length': 4, + '0': 1, + '1': 2, + '2': 3, + '3': 4 + }; + expected = { + 'length': 4, + '0': 1, + '1': 2, + '2': 3, + '3': 4 + }; + actual = fill( x, 5, 3, x.length-1 ); + + t.strictEqual( actual, x, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns an empty array if provided an array of length `0`', function test( t ) { + var expected; + var actual; + + expected = []; + actual = fill( [], 5, 0, 0 ); + + t.deepEqual( actual, expected, 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/filled3d-by/README.md b/lib/node_modules/@stdlib/array/base/filled3d-by/README.md index 6d70dba2a097..ea0c57043e02 100644 --- a/lib/node_modules/@stdlib/array/base/filled3d-by/README.md +++ b/lib/node_modules/@stdlib/array/base/filled3d-by/README.md @@ -134,6 +134,12 @@ out = filled3dBy( [ 1, 1, 3 ], constantFunction( void 0 ) ); @@ -142,6 +148,12 @@ out = filled3dBy( [ 1, 1, 3 ], constantFunction( void 0 ) ); diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/README.md b/lib/node_modules/@stdlib/array/base/indices-complement/README.md new file mode 100644 index 000000000000..4707b4ed3ebd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/README.md @@ -0,0 +1,126 @@ + + +# indicesComplement + +> Return the complement of a list of array indices. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var indicesComplement = require( '@stdlib/array/base/indices-complement' ); +``` + +#### indicesComplement( N, indices ) + +Returns the complement of a list of array indices. + +```javascript +var idx = indicesComplement( 5, [ 1, 2 ] ); +// returns [ 0, 3, 4 ] +``` + +The function accepts the following arguments: + +- **N**: array length. +- **indices**: list of indices from which to derive the complement. + +
+ + + + + +
+ +## Notes + +- The function **always** returns a new "generic" array. + +
+ + + + + +
+ +## Examples + + + +```javascript +var indicesComplement = require( '@stdlib/array/base/indices-complement' ); + +var out = indicesComplement( 5, [ 1, 3, 4 ] ); +// returns [ 0, 2 ] + +out = indicesComplement( 5, [ 0, 1 ] ); +// returns [ 2, 3, 4 ] + +out = indicesComplement( 5, [ 0 ] ); +// returns [ 1, 2, 3, 4 ] + +out = indicesComplement( 5, [] ); +// returns [ 0, 1, 2, 3, 4 ] + +out = indicesComplement( 5, [ 0, 1, 2, 3, 4 ] ); +// returns [] +``` + +
+ + + + + +
+ +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/indices-complement/benchmark/benchmark.js new file mode 100644 index 000000000000..621c8fa4c18e --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/benchmark/benchmark.js @@ -0,0 +1,58 @@ +/** +* @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 isNonNegativeIntegerArray = require( '@stdlib/assert/is-nonnegative-integer-array' ).primitives; +var pkg = require( './../package.json' ).name; +var indicesComplement = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var values; + var out; + var i; + + values = [ + [ 0, 1 ], + [ 0, 1, 2, 3 ], + [ 0 ], + [], + [ 3, 4 ], + [ 1, 3, 4 ] + ]; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + out = indicesComplement( 5, values[ i%values.length ] ); + if ( typeof out !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isNonNegativeIntegerArray( out ) ) { + b.fail( 'should return an array of nonnegative integers' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/docs/repl.txt b/lib/node_modules/@stdlib/array/base/indices-complement/docs/repl.txt new file mode 100644 index 000000000000..473054b50842 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/docs/repl.txt @@ -0,0 +1,25 @@ + +{{alias}}( N, indices ) + Returns the complement of a list of array indices. + + Parameters + ---------- + N: integer + Array length. + + indices: Collection + List of indices from which to derive the complement. + + Returns + ------- + out: Array + Indices complement. + + Examples + -------- + > var idx = {{alias}}( 5, [ 1, 3 ] ) + [ 0, 2, 4 ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/indices-complement/docs/types/index.d.ts new file mode 100644 index 000000000000..72facd9cb536 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/docs/types/index.d.ts @@ -0,0 +1,41 @@ +/* +* @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 + +/// + +import { Collection } from '@stdlib/types/array'; + +/** +* Returns the complement of a list of array indices. +* +* @param N - array length +* @param indices - list of indices +* @returns indices complement +* +* @example +* var idx = indicesComplement( 5, [ 1, 3 ] ); +* // returns [ 0, 2, 4 ] +*/ +declare function indicesComplement( N: number, indices: Collection ): Array; + + +// EXPORTS // + +export = indicesComplement; diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/indices-complement/docs/types/test.ts new file mode 100644 index 000000000000..83338158be89 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/docs/types/test.ts @@ -0,0 +1,56 @@ +/* +* @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. +*/ + +import indicesComplement = require( './index' ); + + +// TESTS // + +// The function returns an array of numbers... +{ + indicesComplement( 5, [ 0, 1 ] ); // $ExpectType number[] +} + +// The compiler throws an error if the function is provided invalid values... +{ + indicesComplement( true, [ 0, 1 ] ); // $ExpectError + indicesComplement( false, [ 0, 1 ] ); // $ExpectError + indicesComplement( '5', [ 0, 1 ] ); // $ExpectError + indicesComplement( [ '5' ], [ 0, 1 ] ); // $ExpectError + indicesComplement( {}, [ 0, 1 ] ); // $ExpectError + indicesComplement( ( x: number ): number => x, [ 0, 1 ] ); // $ExpectError + + indicesComplement( 5, true ); // $ExpectError + indicesComplement( 5, false ); // $ExpectError + indicesComplement( 5, '5' ); // $ExpectError + indicesComplement( 5, 5 ); // $ExpectError + indicesComplement( 5, {} ); // $ExpectError + indicesComplement( 5, ( x: number ): number => x ); // $ExpectError + + indicesComplement( [], true ); // $ExpectError + indicesComplement( {}, false ); // $ExpectError + indicesComplement( false, '5' ); // $ExpectError + indicesComplement( {}, [] ); // $ExpectError + indicesComplement( '5', ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided insufficient arguments... +{ + indicesComplement(); // $ExpectError + indicesComplement( 5 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/examples/index.js b/lib/node_modules/@stdlib/array/base/indices-complement/examples/index.js new file mode 100644 index 000000000000..fc6c316f066f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/examples/index.js @@ -0,0 +1,41 @@ +/** +* @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'; + +var indicesComplement = require( './../lib' ); + +var out = indicesComplement( 5, [ 1, 3, 4 ] ); +console.log( out ); +// => [ 0, 2 ] + +out = indicesComplement( 5, [ 0, 1 ] ); +console.log( out ); +// => [ 2, 3, 4 ] + +out = indicesComplement( 5, [ 0 ] ); +console.log( out ); +// => [ 1, 2, 3, 4 ] + +out = indicesComplement( 5, [] ); +console.log( out ); +// => [ 0, 1, 2, 3, 4 ] + +out = indicesComplement( 5, [ 0, 1, 2, 3, 4 ] ); +console.log( out ); +// => [] diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/lib/index.js b/lib/node_modules/@stdlib/array/base/indices-complement/lib/index.js new file mode 100644 index 000000000000..41e1087ce3b3 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/lib/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +/** +* Return the complement of a list of array indices. +* +* @module @stdlib/array/base/indices-complement +* +* @example +* var indicesComplement = require( '@stdlib/array/base/indices-complement' ); +* +* var idx = indicesComplement( 5, [ 1, 2 ] ); +* // returns [ 0, 3, 4 ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/lib/main.js b/lib/node_modules/@stdlib/array/base/indices-complement/lib/main.js new file mode 100644 index 000000000000..b8ad6da913fd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/lib/main.js @@ -0,0 +1,55 @@ +/** +* @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'; + +// MAIN // + +/** +* Returns the complement of a list of array indices. +* +* @param {NonNegativeInteger} N - array length +* @param {NonNegativeIntegerArray} indices - list of indices +* @returns {NonNegativeIntegerArray} indices complement +* +* @example +* var idx = indicesComplement( 5, [ 1, 2 ] ); +* // returns [ 0, 3, 4 ] +*/ +function indicesComplement( N, indices ) { + var hash; + var out; + var i; + + hash = {}; + for ( i = 0; i < indices.length; i++ ) { + hash[ indices[ i ] ] = true; + } + out = []; + for ( i = 0; i < N; i++ ) { + if ( hash[ i ] === void 0 ) { + out.push( i ); + } + } + return out; +} + + +// EXPORTS // + +module.exports = indicesComplement; diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/package.json b/lib/node_modules/@stdlib/array/base/indices-complement/package.json new file mode 100644 index 000000000000..cae90e96d456 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/package.json @@ -0,0 +1,66 @@ +{ + "name": "@stdlib/array/base/indices-complement", + "version": "0.0.0", + "description": "Return the complement of a list of array indices.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "base", + "array", + "indices", + "index", + "idx", + "ind", + "complement", + "utilities", + "utility", + "utils", + "util" + ], + "__stdlib__": {} +} diff --git a/lib/node_modules/@stdlib/array/base/indices-complement/test/test.js b/lib/node_modules/@stdlib/array/base/indices-complement/test/test.js new file mode 100644 index 000000000000..5ec88a8cc2ef --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/indices-complement/test/test.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 tape = require( 'tape' ); +var isArray = require( '@stdlib/assert/is-array' ); +var indicesComplement = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof indicesComplement, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function returns the complement of a list of indices', function test( t ) { + var expected; + var actual; + var idx; + + idx = [ 0, 2, 3 ]; + expected = [ 1, 4 ]; + + actual = indicesComplement( 5, idx ); + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.notEqual( actual, idx, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + idx = [ 0, 2, 3 ]; + expected = [ 1, 4, 5, 6, 7, 8, 9 ]; + + actual = indicesComplement( 10, idx ); + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.notEqual( actual, idx, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + idx = [ 0, 1, 2, 3, 4 ]; + expected = []; + + actual = indicesComplement( 5, idx ); + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.notEqual( actual, idx, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + idx = []; + expected = [ 0, 1, 2, 3, 4 ]; + + actual = indicesComplement( 5, idx ); + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.notEqual( actual, idx, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/lib/index.js b/lib/node_modules/@stdlib/array/base/lib/index.js index f2e24f3c0a8a..810a98e2856a 100644 --- a/lib/node_modules/@stdlib/array/base/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/lib/index.js @@ -324,6 +324,33 @@ setReadOnly( ns, 'bbinary5d', require( '@stdlib/array/base/broadcasted-binary5d' */ setReadOnly( ns, 'bquaternary2d', require( '@stdlib/array/base/broadcasted-quaternary2d' ) ); +/** +* @name bquaternary3d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-quaternary3d} +*/ +setReadOnly( ns, 'bquaternary3d', require( '@stdlib/array/base/broadcasted-quaternary3d' ) ); + +/** +* @name bquaternary4d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-quaternary4d} +*/ +setReadOnly( ns, 'bquaternary4d', require( '@stdlib/array/base/broadcasted-quaternary4d' ) ); + +/** +* @name bquaternary5d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-quaternary5d} +*/ +setReadOnly( ns, 'bquaternary5d', require( '@stdlib/array/base/broadcasted-quaternary5d' ) ); + /** * @name bquinary2d * @memberof ns @@ -333,6 +360,15 @@ setReadOnly( ns, 'bquaternary2d', require( '@stdlib/array/base/broadcasted-quate */ setReadOnly( ns, 'bquinary2d', require( '@stdlib/array/base/broadcasted-quinary2d' ) ); +/** +* @name bquinary4d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-quinary4d} +*/ +setReadOnly( ns, 'bquinary4d', require( '@stdlib/array/base/broadcasted-quinary4d' ) ); + /** * @name bternary2d * @memberof ns @@ -342,6 +378,33 @@ setReadOnly( ns, 'bquinary2d', require( '@stdlib/array/base/broadcasted-quinary2 */ setReadOnly( ns, 'bternary2d', require( '@stdlib/array/base/broadcasted-ternary2d' ) ); +/** +* @name bternary3d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-ternary3d} +*/ +setReadOnly( ns, 'bternary3d', require( '@stdlib/array/base/broadcasted-ternary3d' ) ); + +/** +* @name bternary4d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-ternary4d} +*/ +setReadOnly( ns, 'bternary4d', require( '@stdlib/array/base/broadcasted-ternary4d' ) ); + +/** +* @name bternary5d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/broadcasted-ternary5d} +*/ +setReadOnly( ns, 'bternary5d', require( '@stdlib/array/base/broadcasted-ternary5d' ) ); + /** * @name bunary2d * @memberof ns @@ -549,6 +612,15 @@ setReadOnly( ns, 'fancySlice', require( '@stdlib/array/base/fancy-slice' ) ); */ setReadOnly( ns, 'fancySliceAssign', require( '@stdlib/array/base/fancy-slice-assign' ) ); +/** +* @name fill +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/fill} +*/ +setReadOnly( ns, 'fill', require( '@stdlib/array/base/fill' ) ); + /** * @name filled * @memberof ns @@ -927,6 +999,15 @@ setReadOnly( ns, 'incrspace', require( '@stdlib/array/base/incrspace' ) ); */ setReadOnly( ns, 'indexOf', require( '@stdlib/array/base/index-of' ) ); +/** +* @name indicesComplement +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/indices-complement} +*/ +setReadOnly( ns, 'indicesComplement', require( '@stdlib/array/base/indices-complement' ) ); + /** * @name join * @memberof ns @@ -1035,6 +1116,33 @@ setReadOnly( ns, 'minUnsignedIntegerDataType', require( '@stdlib/array/base/min- */ setReadOnly( ns, 'mskbinary2d', require( '@stdlib/array/base/mskbinary2d' ) ); +/** +* @name mskbinary3d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskbinary3d} +*/ +setReadOnly( ns, 'mskbinary3d', require( '@stdlib/array/base/mskbinary3d' ) ); + +/** +* @name mskbinary4d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskbinary4d} +*/ +setReadOnly( ns, 'mskbinary4d', require( '@stdlib/array/base/mskbinary4d' ) ); + +/** +* @name mskbinary5d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskbinary5d} +*/ +setReadOnly( ns, 'mskbinary5d', require( '@stdlib/array/base/mskbinary5d' ) ); + /** * @name mskfilter * @memberof ns @@ -1044,6 +1152,33 @@ setReadOnly( ns, 'mskbinary2d', require( '@stdlib/array/base/mskbinary2d' ) ); */ setReadOnly( ns, 'mskfilter', require( '@stdlib/array/base/mskfilter' ) ); +/** +* @name mskfilterMap +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskfilter-map} +*/ +setReadOnly( ns, 'mskfilterMap', require( '@stdlib/array/base/mskfilter-map' ) ); + +/** +* @name mskfilter2 +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskfilter2} +*/ +setReadOnly( ns, 'mskfilter2', require( '@stdlib/array/base/mskfilter2' ) ); + +/** +* @name mskfiltern +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskfiltern} +*/ +setReadOnly( ns, 'mskfiltern', require( '@stdlib/array/base/mskfiltern' ) ); + /** * @name mskput * @memberof ns @@ -1080,6 +1215,24 @@ setReadOnly( ns, 'mskunary2d', require( '@stdlib/array/base/mskunary2d' ) ); */ setReadOnly( ns, 'mskunary3d', require( '@stdlib/array/base/mskunary3d' ) ); +/** +* @name mskunary4d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskunary4d} +*/ +setReadOnly( ns, 'mskunary4d', require( '@stdlib/array/base/mskunary4d' ) ); + +/** +* @name mskunary5d +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/mskunary5d} +*/ +setReadOnly( ns, 'mskunary5d', require( '@stdlib/array/base/mskunary5d' ) ); + /** * @name nCartesianProduct * @memberof ns @@ -1323,6 +1476,24 @@ setReadOnly( ns, 'resolveSetter', require( '@stdlib/array/base/resolve-setter' ) */ setReadOnly( ns, 'reverse', require( '@stdlib/array/base/reverse' ) ); +/** +* @name scatterFilled +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/scatter-filled} +*/ +setReadOnly( ns, 'scatterFilled', require( '@stdlib/array/base/scatter-filled' ) ); + +/** +* @name scattered +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/scattered} +*/ +setReadOnly( ns, 'scattered', require( '@stdlib/array/base/scattered' ) ); + /** * @name setter * @memberof ns @@ -1395,6 +1566,15 @@ setReadOnly( ns, 'take', require( '@stdlib/array/base/take' ) ); */ setReadOnly( ns, 'takeIndexed', require( '@stdlib/array/base/take-indexed' ) ); +/** +* @name takeIndexed2 +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/take-indexed2} +*/ +setReadOnly( ns, 'takeIndexed2', require( '@stdlib/array/base/take-indexed2' ) ); + /** * @name take2d * @memberof ns @@ -1503,6 +1683,15 @@ setReadOnly( ns, 'unary2dBy', require( '@stdlib/array/base/unary2d-by' ) ); */ setReadOnly( ns, 'unary3d', require( '@stdlib/array/base/unary3d' ) ); +/** +* @name unary3dBy +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/unary3d-by} +*/ +setReadOnly( ns, 'unary3dBy', require( '@stdlib/array/base/unary3d-by' ) ); + /** * @name unary4d * @memberof ns @@ -1512,6 +1701,15 @@ setReadOnly( ns, 'unary3d', require( '@stdlib/array/base/unary3d' ) ); */ setReadOnly( ns, 'unary4d', require( '@stdlib/array/base/unary4d' ) ); +/** +* @name unary4dBy +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/unary4d-by} +*/ +setReadOnly( ns, 'unary4dBy', require( '@stdlib/array/base/unary4d-by' ) ); + /** * @name unary5d * @memberof ns @@ -1521,6 +1719,15 @@ setReadOnly( ns, 'unary4d', require( '@stdlib/array/base/unary4d' ) ); */ setReadOnly( ns, 'unary5d', require( '@stdlib/array/base/unary5d' ) ); +/** +* @name unary5dBy +* @memberof ns +* @readonly +* @type {Function} +* @see {@link module:@stdlib/array/base/unary5d-by} +*/ +setReadOnly( ns, 'unary5dBy', require( '@stdlib/array/base/unary5d-by' ) ); + /** * @name unarynd * @memberof ns diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/README.md b/lib/node_modules/@stdlib/array/base/mskfilter-map/README.md index 07368993beef..a617ee2cd7ba 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/README.md +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/README.md @@ -20,7 +20,7 @@ limitations under the License. # mskfilterMap -> Apply a mask to a provided input array and return a new array after applying a mapping function. +> Apply a mask and a callback function to a provided input array.
@@ -32,7 +32,7 @@ var mskfilterMap = require( '@stdlib/array/base/mskfilter-map' ); #### mskfilterMap( x, mask, clbk\[, thisArg] ) -Applies a mask to a provided input array and returns a new array after applying a mapping function. +Returns a new array after applying a mask and a callback function to a provided input array. ```javascript function clbk( value ) { @@ -50,10 +50,10 @@ The function supports the following parameters: - **x**: input array. - **mask**: mask array. -- **clbk**: function to apply. -- **thisArg**: applied function execution context (_optional_). +- **clbk**: callback to apply. +- **thisArg**: callback execution context (_optional_). -To set the applied function's execution context, provide a `thisArg`. +To set the execution context of the callback function, provide a `thisArg`. @@ -81,7 +81,7 @@ The function **always** returns a new "generic" array. #### mskfilterMap.assign( x, mask, out, stride, offset, clbk\[, thisArg] ) -Applies a mask and mapping function to a provided input array and assigns results to elements in a provided output array. +Applies a mask and a callback function to a provided input array and assigns results to elements in a provided output array. ```javascript function clbk( value ) { @@ -106,8 +106,8 @@ The function supports the following parameters: - **out**: output array. - **stride**: output array stride. - **offset**: output array offset. -- **clbk**: function to apply. -- **thisArg**: applied function execution context (_optional_). +- **clbk**: callback function. +- **thisArg**: callback execution context (_optional_).
diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.assign.length.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.assign.length.js index 3a6e2bd75bc5..1ce5e32f264c 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.assign.length.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.assign.length.js @@ -27,7 +27,7 @@ var zeros = require( '@stdlib/array/zeros' ); var ones = require( '@stdlib/array/ones' ); var isArray = require( '@stdlib/assert/is-array' ); var isnan = require( '@stdlib/assert/is-nan' ).isPrimitive; -var identity = require( '@stdlib/math/base/special/identity' ); +var identity = require( '@stdlib/utils/identity-function' ); var pkg = require( './../package.json' ).name; var mskfilterMap = require( './../lib' ); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.js index 8a65993f2f60..86c146b031db 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.js @@ -24,7 +24,7 @@ var bench = require( '@stdlib/bench' ); var isArray = require( '@stdlib/assert/is-array' ); var zeroTo = require( '@stdlib/array/base/zero-to' ); var ones = require( '@stdlib/array/base/ones' ); -var identity = require( '@stdlib/math/base/special/identity' ); +var identity = require( '@stdlib/utils/identity-function' ); var pkg = require( './../package.json' ).name; var mskfilterMap = require( './../lib' ); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.length.js index ba417028e9df..e095ad90d077 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.length.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/benchmark/benchmark.length.js @@ -25,7 +25,7 @@ var pow = require( '@stdlib/math/base/special/pow' ); var zeroTo = require( '@stdlib/array/base/zero-to' ); var ones = require( '@stdlib/array/base/ones' ); var isArray = require( '@stdlib/assert/is-array' ); -var identity = require( '@stdlib/math/base/special/identity' ); +var identity = require( '@stdlib/utils/identity-function' ); var pkg = require( './../package.json' ).name; var mskfilterMap = require( './../lib' ); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/repl.txt b/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/repl.txt index 5ab7835f7c17..34e90a68eb81 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/repl.txt +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/repl.txt @@ -1,7 +1,7 @@ -{{alias}}( x, mask, fcn[, thisArg] ) - Applies a mask to a provided input array and returns a new array after - applying a mapping function. +{{alias}}( x, mask, clbk[, thisArg] ) + Returns a new array after applying a mask and a callback function to a + provided input array. If a mask array element is truthy, the corresponding element in `x` is included in the output array; otherwise, the corresponding element in `x` @@ -15,11 +15,11 @@ mask: ArrayLikeObject Mask array. - fcn: Function + clbk: Function Function to apply. thisArg: any (optional) - Function execution context. + Callback execution context. Returns ------- @@ -33,8 +33,8 @@ [ 2, 4 ] -{{alias}}.assign( x, mask, out, stride, offset, fcn[, thisArg] ) - Applies a mask and mapping function to a provided input array and assigns +{{alias}}.assign( x, mask, out, stride, offset, clbk[, thisArg] ) + Applies a mask and a callback function to a provided input array and assigns results to elements in a provided output array. If a mask array element is truthy, the corresponding element in `x` is @@ -58,11 +58,11 @@ offset: integer Output array offset. - fcn: Function + clbk: Function Function to apply. thisArg: any (optional) - Function execution context. + Callback execution context. Returns ------- diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/index.d.ts index bbf5f503d4d4..708c4f8a5c73 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { Array2D, Collection } from '@stdlib/types/array'; +import { Collection } from '@stdlib/types/array'; /** * Callback invoked for each array element. @@ -41,7 +41,7 @@ type Unary = ( this: V, value: T ) => U; * Callback invoked for each array element. * * @param value - array element -* @param indices - current array element indices +* @param index - current array element index * @returns result */ type Binary = ( this: V, value: T, index: number ) => U; @@ -50,17 +50,17 @@ type Binary = ( this: V, value: T, index: number ) => U; * Callback invoked for each array element. * * @param value - array element -* @param indices - current array element indices +* @param index - current array element index * @param array - input array * @returns result */ -type Ternary = ( this: V, value: T, index: number, array: Array2D ) => U; +type Ternary = ( this: V, value: T, index: number, array: Collection ) => U; /** * Callback invoked for each array element. * * @param value - array element -* @param indices - current array element indices +* @param index - current array element index * @param array - input array * @returns result */ @@ -71,12 +71,12 @@ type Callback = Nullary | Unary | Binary | Tern */ interface Routine { /** - * Applies a mask to a provided input array and returns a new array after applying a mapping function. + * Returns a new array after applying a mask and a callback function to a provided input array. * * @param x - input array * @param mask - mask array - * @param clbk - callback to invoke - * @param thisArg - execution context + * @param clbk - callback function + * @param thisArg - callback execution context * @returns output array * * @example @@ -92,15 +92,15 @@ interface Routine { ( x: Collection, mask: Collection, clbk: Callback, thisArg?: ThisParameterType> ): Array; /** - * Applies a mask and mapping function to an input array and assigns results to elements in an output array. + * Applies a mask and a callback function to an input array and assigns results to elements in an output array. * * @param x - input array * @param mask - mask array * @param out - output array * @param stride - output array stride * @param offset - output array offset - * @param clbk - callback to invoke - * @param thisArg - execution context + * @param clbk - callback function + * @param thisArg - callback execution context * @returns output array * * @example @@ -123,12 +123,12 @@ interface Routine { } /** -* Applies a mask to a provided input array and returns a new array after applying a mapping function. +* Returns a new array after applying a mask and a callback function to a provided input array. * * @param x - input array * @param mask - mask array -* @param clbk - callback to invoke -* @param thisArg - execution context +* @param clbk - callback function +* @param thisArg - callback execution context * @returns output array * * @example diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/test.ts index 38f6761d45d0..45029b41f407 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/test.ts +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/docs/types/test.ts @@ -19,7 +19,7 @@ import mskfilterMap = require( './index' ); /** -* Unary function. +* Callback function. * * @param value - input value * @returns result @@ -250,6 +250,7 @@ function clbk( value: number ): number { const mask = [ 0.0, 0.0, 0.0, 0.0 ]; mskfilterMap.assign(); // $ExpectError + mskfilterMap.assign( x ); // $ExpectError mskfilterMap.assign( x, mask ); // $ExpectError mskfilterMap.assign( x, mask, [ 0, 0, 0, 0 ] ); // $ExpectError mskfilterMap.assign( x, mask, [ 0, 0, 0, 0 ], 1 ); // $ExpectError diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/assign.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/assign.js index 49189a7425cc..fb398861cbc1 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/assign.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/assign.js @@ -26,7 +26,7 @@ var arraylike2object = require( '@stdlib/array/base/arraylike2object' ); // FUNCTIONS // /** -* Applies a mask and mapping function to an indexed array and assigns results to elements in an indexed output array. +* Applies a mask and a callback function to an indexed array and assigns results to elements in an indexed output array. * * @private * @param {Collection} x - input array @@ -35,7 +35,7 @@ var arraylike2object = require( '@stdlib/array/base/arraylike2object' ); * @param {integer} stride - output array stride * @param {NonNegativeInteger} offset - output array offset * @param {Function} clbk - function to apply -* @param {*} [thisArg] - function execution context +* @param {*} [thisArg] - callback execution context * @returns {Collection} output array * * @example @@ -66,7 +66,7 @@ function indexed( x, mask, out, stride, offset, clbk, thisArg ) { } /** -* Applies a mask and mapping function to an input accessor array and assigns results to elements in an output accessor array. +* Applies a mask and a callback function to an input accessor array and assigns results to elements in an output accessor array. * * @private * @param {Object} x - input array object @@ -75,7 +75,7 @@ function indexed( x, mask, out, stride, offset, clbk, thisArg ) { * @param {integer} stride - output array stride * @param {NonNegativeInteger} offset - output array offset * @param {Function} clbk - function to apply -* @param {*} [thisArg] - function execution context +* @param {*} [thisArg] - callback execution context * @returns {Collection} output array * * @example @@ -130,7 +130,7 @@ function accessors( x, mask, out, stride, offset, clbk, thisArg ) { // MAIN // /** -* Applies a mask and mapping function to a provided input array and assigns results to elements in a provided output array. +* Applies a mask and a callback function to a provided input array and assigns results to elements in a provided output array. * * @param {Collection} x - input array * @param {Collection} mask - mask array @@ -138,7 +138,7 @@ function accessors( x, mask, out, stride, offset, clbk, thisArg ) { * @param {integer} stride - output array stride * @param {NonNegativeInteger} offset - output array offset * @param {Function} clbk - function to apply -* @param {*} [thisArg] - function execution context +* @param {*} [thisArg] - callback execution context * @returns {Collection} output array * * @example diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/index.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/index.js index c131c816d6e9..f9f77206a282 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/index.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/index.js @@ -19,7 +19,7 @@ 'use strict'; /** -* Apply a mask to a provided input array and return a new array after applying a mapping function. +* Apply a mask and a callback function to a provided input array. * * @module @stdlib/array/base/mskfilter-map * diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/main.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/main.js index 9f860bbaddd2..048d4a20b552 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/main.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/lib/main.js @@ -26,12 +26,12 @@ var resolveGetter = require( '@stdlib/array/base/resolve-getter' ); // MAIN // /** -* Apply a mask to a provided input array and returns a new array after applying a mapping function. +* Returns a new array after applying a mask and a callback function to a provided input array. * * @param {Collection} x - input array * @param {Collection} mask - mask array -* @param {Function} clbk - callback to invoke -* @param {*} [thisArg] - execution context +* @param {Function} clbk - callback function +* @param {*} [thisArg] - callback execution context * @returns {Array} output array * * @example diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/package.json b/lib/node_modules/@stdlib/array/base/mskfilter-map/package.json index c0b047cd7bc1..a9d9574c49f2 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/package.json +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/package.json @@ -1,7 +1,7 @@ { "name": "@stdlib/array/base/mskfilter-map", "version": "0.0.0", - "description": "Apply a mask to a provided input array.", + "description": "Apply a mask and a callback function to a provided input array.", "license": "Apache-2.0", "author": { "name": "The Stdlib Authors", diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.assign.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.assign.js index a70f3c13ee05..9c60949e92ae 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.assign.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.assign.js @@ -21,9 +21,9 @@ // MODULES // var tape = require( 'tape' ); +var isSameComplex64Array = require( '@stdlib/assert/is-same-complex64array' ); var Complex64Array = require( '@stdlib/array/complex64' ); var toAccessorArray = require( '@stdlib/array/base/to-accessor-array' ); -var reinterpret = require( '@stdlib/strided/base/reinterpret-complex' ); var Int32Array = require( '@stdlib/array/int32' ); var zeros = require( '@stdlib/array/zeros' ); var mskfilterMap = require( './../lib' ).assign; @@ -88,8 +88,8 @@ tape( 'the function filters array elements (generic)', function test( t ) { t.end(); - function clbk( val ) { - return val * val; + function clbk( v ) { + return v * v; } }); @@ -144,8 +144,8 @@ tape( 'the function filters array elements (real typed array)', function test( t t.end(); - function clbk( val ) { - return val * val; + function clbk( v ) { + return v * v; } }); @@ -156,59 +156,52 @@ tape( 'the function filters array elements (complex typed array)', function test var out; var x; - x = reinterpret(new Complex64Array( [ 1.0, 2.0, 3.0, 4.0 ] ) ); + x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0 ] ); mask = [ 1, 0 ]; - out = reinterpret( zeros( 1, 'complex64' ) ); + out = zeros( 1, 'complex64' ); actual = mskfilterMap( x, mask, out, 1, 0, clbk ); - expected = reinterpret( new Complex64Array( [ 1.0, 4.0, 25.0, 36.0 ] ) ); + expected = new Complex64Array( [ 1.0, 2.0 ] ); t.strictEqual( actual, out, 'returns expected value' ); - isEqual( actual, expected ); + t.strictEqual( isSameComplex64Array( actual, expected ), true, 'returns expected value' ); mask = [ 0, 0 ]; - out = reinterpret( zeros( 0, 'complex64' ) ); + out = zeros( 0, 'complex64' ); actual = mskfilterMap( x, mask, out, 1, 0, clbk ); - expected = reinterpret( new Complex64Array( [] ) ); + expected = new Complex64Array( [] ); t.strictEqual( actual, out, 'returns expected value' ); - isEqual( actual, expected ); + t.strictEqual( isSameComplex64Array( actual, expected ), true, 'returns expected value' ); mask = [ 0, 1 ]; - out = reinterpret( zeros( 1, 'complex64' ) ); + out = zeros( 1, 'complex64' ); actual = mskfilterMap( x, mask, out, 1, 0, clbk ); - expected = reinterpret( new Complex64Array( [ 9.0, 16.0 ] ) ); + expected = new Complex64Array( [ 3.0, 4.0 ] ); t.strictEqual( actual, out, 'returns expected value' ); - isEqual( actual, expected ); + t.strictEqual( isSameComplex64Array( actual, expected ), true, 'returns expected value' ); mask = [ 1, 1 ]; - out = reinterpret( zeros( 3, 'complex64' ) ); + out = zeros( 3, 'complex64' ); actual = mskfilterMap( x, mask, out, 1, 0, clbk ); - expected = reinterpret( new Complex64Array( [ 1.0, 4.0, 9.0, 16.0 ] ) ); + expected = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 0.0, 0.0 ] ); t.strictEqual( actual, out, 'returns expected value' ); - isEqual( actual, expected ); + t.strictEqual( isSameComplex64Array( actual, expected ), true, 'returns expected value' ); mask = [ 1, 0 ]; - out = reinterpret( zeros( 3, 'complex64' ) ); + out = zeros( 3, 'complex64' ); actual = mskfilterMap( x, mask, out, -2, out.length-1, clbk ); - expected = reinterpret( new Complex64Array( [ 0.0, 0.0, 1.0, 4.0 ] ) ); + expected = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0, 1.0, 2.0 ] ); t.strictEqual( actual, out, 'returns expected value' ); - isEqual( actual, expected ); + t.strictEqual( isSameComplex64Array( actual, expected ), true, 'returns expected value' ); t.end(); - function isEqual( actual, expected ) { - var i; - for ( i = 0; i < expected.length; i++ ) { - t.strictEqual( actual.get( i ), expected[ i ], 'returns expected value' ); - } - } - - function clbk( val ) { - return val * val; + function clbk( v ) { + return v; } }); @@ -263,19 +256,19 @@ tape( 'the function filters array elements (accessors)', function test( t ) { t.end(); + function clbk( v ) { + return v * v; + } + function isEqual( actual, expected ) { var i; for ( i = 0; i < expected.length; i++ ) { t.strictEqual( actual.get( i ), expected[ i ], 'returns expected value' ); } } - - function clbk( val ) { - return val * val; - } }); -tape( 'the function returns leaves an output array unchanged if provided a second argument having all element equal to zero ', function test( t ) { +tape( 'the function returns leaves an output array unchanged if provided a second argument having all elements equal to zero ', function test( t ) { var expected; var actual; var mask; @@ -304,22 +297,15 @@ tape( 'the function returns leaves an output array unchanged if provided a secon mask = [ 0, 0 ]; - x = reinterpret( new Complex64Array( [ 1.0, 2.0, 3.0, 4.0 ] ) ); - out = reinterpret( new Complex64Array( [ 0.0, 0.0, 0.0, 0.0 ] ) ); - expected = reinterpret( new Complex64Array( [ 0.0, 0.0, 0.0, 0.0 ] ) ); + x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0 ] ); + out = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0 ] ); + expected = new Complex64Array( [ 0.0, 0.0, 0.0, 0.0 ] ); actual = mskfilterMap( x, mask, out, 1, 0, clbk ); - isEqual( actual, expected ); + t.strictEqual( isSameComplex64Array( actual, expected ), true, 'returns expected value' ); t.end(); - function isEqual( actual, expected ) { - var i; - for ( i = 0; i < expected.length; i++ ) { - t.strictEqual( actual.get( i ), expected[ i ], 'returns expected value' ); - } - } - - function clbk( val ) { - return val * val; + function clbk( v ) { + return v * v; } }); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.main.js b/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.main.js index 7429251591e4..6f74254c1ceb 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.main.js +++ b/lib/node_modules/@stdlib/array/base/mskfilter-map/test/test.main.js @@ -73,8 +73,8 @@ tape( 'the function filters array elements', function test( t ) { t.end(); - function clbk( val ) { - return val * val; + function clbk( v ) { + return v * v; } }); @@ -97,8 +97,8 @@ tape( 'the function filters array elements (accessors)', function test( t ) { } t.end(); - function clbk( val ) { - return val; + function clbk( v ) { + return v; } }); @@ -106,12 +106,12 @@ tape( 'the function returns an empty array if provided empty arrays', function t t.deepEqual( mskfilterMap( [], [], clbk ), [], 'returns expected value' ); t.end(); - function clbk( val ) { - return val * val; + function clbk( v ) { + return v * v; } }); -tape( 'the function supports providing a function execution context', function test( t ) { +tape( 'the function supports providing a callback execution context', function test( t ) { var expected; var indices; var values; diff --git a/lib/node_modules/@stdlib/array/base/mskfilter/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/mskfilter/docs/types/test.ts index 77689758fbc1..b00a181e8d7d 100644 --- a/lib/node_modules/@stdlib/array/base/mskfilter/docs/types/test.ts +++ b/lib/node_modules/@stdlib/array/base/mskfilter/docs/types/test.ts @@ -39,7 +39,7 @@ import mskfilter = require( './index' ); mskfilter( {}, [ 0, 0 ] ); // $ExpectError } -// The compiler throws an error if the function is provided a second argument which is not an array-like object containing numbers... +// The compiler throws an error if the function is provided a second argument which is not an array-like object... { mskfilter( [], 1 ); // $ExpectError mskfilter( [], true ); // $ExpectError diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/README.md b/lib/node_modules/@stdlib/array/base/mskfilter2/README.md new file mode 100644 index 000000000000..2a2996f675a3 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/README.md @@ -0,0 +1,114 @@ + + +# mskfilter2 + +> Apply a mask to two provided input arrays in a single pass. + +
+ +## Usage + +```javascript +var mskfilter2 = require( '@stdlib/array/base/mskfilter2' ); +``` + +#### mskfilter2( x, y, mask ) + +Returns new arrays by applying a mask to two provided input arrays in a single pass. + +```javascript +var x = [ 1, 2, 3, 4 ]; +var y = [ 0, 1, 2, 3 ]; + +var out = mskfilter2( x, y, [ 0, 1, 0, 1 ] ); +// returns [ [ 2, 4 ], [ 1, 3 ] ] +``` + +The function supports the following parameters: + +- **x**: first input array. +- **y**: second input array. +- **mask**: mask array. + +The function **always** returns new "generic" arrays. + +
+ + + +
+ +## Notes + +- If a `mask` array element is truthy, the corresponding elements in the input arrays are **included** in the respective output arrays; otherwise, the corresponding elements in the input arrays are "masked" and thus **excluded** from the respective output arrays. + +
+ + + +
+ +## Examples + + + +```javascript +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var bernoulli = require( '@stdlib/random/array/bernoulli' ); +var mskfilter2 = require( '@stdlib/array/base/mskfilter2' ); + +// Generate linearly spaced arrays: +var x = zeroTo( 20 ); +console.log( x ); + +var y = zeroTo( x.length ); +console.log( y ); + +// Generate a random mask: +var mask = bernoulli( x.length, 0.5, { + 'dtype': 'generic' +}); +console.log( mask ); + +// Filter both arrays using the mask: +var out = mskfilter2( x, y, mask ); +console.log( out ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/mskfilter2/benchmark/benchmark.js new file mode 100644 index 000000000000..62a2b7786d5f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/benchmark/benchmark.js @@ -0,0 +1,55 @@ +/** +* @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 isArrayArray = require( '@stdlib/assert/is-array-array' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var ones = require( '@stdlib/array/base/ones' ); +var pkg = require( './../package.json' ).name; +var mskfilter2 = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::copy:len=100', function benchmark( b ) { + var x; + var y; + var i; + var v; + + x = zeroTo( 100 ); + y = ones( x.length ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = mskfilter2( x, x, y ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isArrayArray( v ) ) { + b.fail( 'should return an array of arrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/mskfilter2/benchmark/benchmark.length.js new file mode 100644 index 000000000000..90a7c730cfe6 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/benchmark/benchmark.length.js @@ -0,0 +1,97 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var ones = require( '@stdlib/array/base/ones' ); +var isArrayArray = require( '@stdlib/assert/is-array-array' ); +var pkg = require( './../package.json' ).name; +var mskfilter2 = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = zeroTo( len ); + var y = ones( len ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var v; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = mskfilter2( x, x, y ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isArrayArray( v ) ) { + b.fail( 'should return an array of arrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/docs/repl.txt b/lib/node_modules/@stdlib/array/base/mskfilter2/docs/repl.txt new file mode 100644 index 000000000000..da35ee919b50 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/docs/repl.txt @@ -0,0 +1,36 @@ + +{{alias}}( x, y, mask ) + Returns new arrays by applying a mask to two provided input arrays in a + single pass. + + If a mask array element is truthy, the corresponding elements in the input + arrays are included in the respective output arrays; otherwise, the + corresponding elements in the input arrays are "masked" and thus excluded + from the output arrays. + + Parameters + ---------- + x: ArrayLikeObject + First input array. + + y: ArrayLikeObject + Second input array. + + mask: ArrayLikeObject + Mask array. + + Returns + ------- + out: Array + Output arrays. + + Examples + -------- + > var x = [ 1, 2, 3, 4 ]; + > var y = [ 0, 1, 2, 3 ]; + > var out = {{alias}}( x, y, [ 0, 1, 0, 1 ] ) + [ [ 2, 4 ], [ 1, 3 ] ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/mskfilter2/docs/types/index.d.ts new file mode 100644 index 000000000000..f5621cdb5e28 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/docs/types/index.d.ts @@ -0,0 +1,46 @@ +/* +* @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 + +/// + +import { Collection } from '@stdlib/types/array'; + +/** +* Returns new arrays by applying a mask to two provided input arrays in a single pass. +* +* @param x - first input array +* @param y - second input array +* @param mask - mask array +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfilter2( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ +declare function mskfilter2( x: Collection, y: Collection, mask: Collection ): [ Array, Array ]; + + +// EXPORTS // + +export = mskfilter2; diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/mskfilter2/docs/types/test.ts new file mode 100644 index 000000000000..aadb9e8f0848 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/docs/types/test.ts @@ -0,0 +1,68 @@ +/* +* @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. +*/ + +import mskfilter2 = require( './index' ); + + +// TESTS // + +// The function returns two arrays... +{ + mskfilter2( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[]] + mskfilter2( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [any[], any[]] + mskfilter2( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[]] + mskfilter2( [ '1', '2', '3', '4' ], [ '1', '2', '3', '4' ], [ 0, 0 ] ); // $ExpectType [string[], string[]] +} + +// The compiler throws an error if the function is provided a first argument which is not an array-like object... +{ + mskfilter2( 1, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfilter2( true, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfilter2( false, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfilter2( null, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfilter2( void 0, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfilter2( {}, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not an array-like object... +{ + mskfilter2( [ 1, 2, 3, 4 ], 1, [ 0, 0 ] ); // $ExpectError + mskfilter2( [ 1, 2, 3, 4 ], true, [ 0, 0 ] ); // $ExpectError + mskfilter2( [ 1, 2, 3, 4 ], false, [ 0, 0 ] ); // $ExpectError + mskfilter2( [ 1, 2, 3, 4 ], null, [ 0, 0 ] ); // $ExpectError + mskfilter2( [ 1, 2, 3, 4 ], void 0, [ 0, 0 ] ); // $ExpectError + mskfilter2( [ 1, 2, 3, 4 ], {}, [ 0, 0 ] ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not an array-like object... +{ + mskfilter2( [], [], 1 ); // $ExpectError + mskfilter2( [], [], true ); // $ExpectError + mskfilter2( [], [], false ); // $ExpectError + mskfilter2( [], [], null ); // $ExpectError + mskfilter2( [], [], void 0 ); // $ExpectError + mskfilter2( [], [], {} ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + mskfilter2(); // $ExpectError + mskfilter2( [] ); // $ExpectError + mskfilter2( [], [] ); // $ExpectError + mskfilter2( [], [], [], [] ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/examples/index.js b/lib/node_modules/@stdlib/array/base/mskfilter2/examples/index.js new file mode 100644 index 000000000000..9310a20fdcea --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/examples/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var bernoulli = require( '@stdlib/random/array/bernoulli' ); +var mskfilter2 = require( './../lib' ); + +// Generate linearly spaced arrays: +var x = zeroTo( 20 ); +console.log( x ); + +var y = zeroTo( x.length ); +console.log( y ); + +// Generate a random mask: +var mask = bernoulli( x.length, 0.5, { + 'dtype': 'generic' +}); +console.log( mask ); + +// Filter both arrays using the mask: +var out = mskfilter2( x, y, mask ); +console.log( out ); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/lib/index.js b/lib/node_modules/@stdlib/array/base/mskfilter2/lib/index.js new file mode 100644 index 000000000000..a0eb1f642ca3 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/lib/index.js @@ -0,0 +1,44 @@ +/** +* @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'; + +/** +* Apply a mask to two provided input arrays in a single pass. +* +* @module @stdlib/array/base/mskfilter2 +* +* @example +* var mskfilter2 = require( '@stdlib/array/base/mskfilter2' ); +* +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfilter2( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/lib/main.js b/lib/node_modules/@stdlib/array/base/mskfilter2/lib/main.js new file mode 100644 index 000000000000..a29774e6f7db --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/lib/main.js @@ -0,0 +1,72 @@ +/** +* @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 resolveGetter = require( '@stdlib/array/base/resolve-getter' ); + + +// MAIN // + +/** +* Returns new arrays by applying a mask to two provided input arrays in a single pass. +* +* @param {Collection} x - first input array +* @param {Collection} y - second input array +* @param {Collection} mask - mask array +* @returns {Array} output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfilter2( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ +function mskfilter2( x, y, mask ) { + var xget; + var yget; + var mget; + var o1; + var o2; + var i; + + // Resolve accessors for retrieving array elements: + xget = resolveGetter( x ); + yget = resolveGetter( y ); + mget = resolveGetter( mask ); + + // Extract each desired element from the provided arrays... + o1 = []; + o2 = []; + for ( i = 0; i < x.length; i++ ) { + if ( mget( mask, i ) ) { + o1.push( xget( x, i ) ); // use `Array#push` to ensure "fast" elements + o2.push( yget( y, i ) ); + } + } + return [ o1, o2 ]; +} + + +// EXPORTS // + +module.exports = mskfilter2; diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/package.json b/lib/node_modules/@stdlib/array/base/mskfilter2/package.json new file mode 100644 index 000000000000..a235eef84199 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/package.json @@ -0,0 +1,65 @@ +{ + "name": "@stdlib/array/base/mskfilter2", + "version": "0.0.0", + "description": "Apply a mask to two provided input arrays in a single pass.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "utilities", + "utils", + "generic", + "array", + "take", + "extract", + "copy", + "index", + "mask", + "filter", + "reject" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/test/test.js b/lib/node_modules/@stdlib/array/base/mskfilter2/test/test.js new file mode 100644 index 000000000000..b346e0768ebd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/test/test.js @@ -0,0 +1,33 @@ +/** +* @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 tape = require( 'tape' ); +var mskfilter2 = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof mskfilter2, 'function', 'main export is a function' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/mskfilter2/test/test.main.js b/lib/node_modules/@stdlib/array/base/mskfilter2/test/test.main.js new file mode 100644 index 000000000000..4d6716db2104 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfilter2/test/test.main.js @@ -0,0 +1,164 @@ +/** +* @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 tape = require( 'tape' ); +var Complex64Array = require( '@stdlib/array/complex64' ); +var BooleanArray = require( '@stdlib/array/bool' ); +var isSameComplex64 = require( '@stdlib/assert/is-same-complex64' ); +var isArray = require( '@stdlib/assert/is-array' ); +var mskfilter2 = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof mskfilter2, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function filters array elements', function test( t ) { + var expected; + var actual; + var mask; + var y; + var x; + + x = [ 1, 2, 3, 4 ]; + y = [ 0, 1, 2, 3 ]; + + mask = [ 0, 1, 0, 1 ]; + actual = mskfilter2( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ 2, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 1, 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + mask = [ 0, 0, 0, 0 ]; + actual = mskfilter2( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = []; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = []; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + mask = [ 0, 0, 0, 1 ]; + actual = mskfilter2( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + mask = [ 1, 1, 1, 1 ]; + actual = mskfilter2( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ 1, 2, 3, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 0, 1, 2, 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function filters array elements (accessors)', function test( t ) { + var expected; + var actual; + var mask; + var y; + var x; + var i; + + x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + y = [ 0, 1, 2, 3 ]; + mask = [ 0, 1, 0, 1 ]; + actual = mskfilter2( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ x.get( 1 ), x.get( 3 ) ]; + for ( i = 0; i < expected.length; i++ ) { + t.strictEqual( isSameComplex64( actual[ 0 ][ i ], expected[ i ] ), true, 'returns expected value' ); + } + expected = [ 1, 3 ]; + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + x = new BooleanArray( [ true, false, false, true ] ); + y = [ 0, 1, 2, 3 ]; + mask = [ 0, 1, 0, 1 ]; + actual = mskfilter2( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ x.get( 1 ), x.get( 3 ) ]; + for ( i = 0; i < expected.length; i++ ) { + t.strictEqual( actual[ 0 ][ i ], expected[ i ], 'returns expected value' ); + } + expected = [ 1, 3 ]; + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns empty arrays if provided empty arrays', function test( t ) { + t.deepEqual( mskfilter2( [], [], [] ), [ [], [] ], 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/README.md b/lib/node_modules/@stdlib/array/base/mskfiltern/README.md new file mode 100644 index 000000000000..95739451c4b5 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/README.md @@ -0,0 +1,114 @@ + + +# mskfiltern + +> Apply a mask to one or more provided input arrays in a single pass. + +
+ +## Usage + +```javascript +var mskfiltern = require( '@stdlib/array/base/mskfiltern' ); +``` + +#### mskfiltern( x, \[...arrays,] mask ) + +Returns new arrays by applying a mask to one or more provided input arrays in a single pass. + +```javascript +var x = [ 1, 2, 3, 4 ]; +var y = [ 0, 1, 2, 3 ]; + +var out = mskfiltern( x, y, [ 0, 1, 0, 1 ] ); +// returns [ [ 2, 4 ], [ 1, 3 ] ] +``` + +The function supports the following parameters: + +- **x**: first input array. +- **...arrays**: additional input arrays. +- **mask**: mask array. + +The function **always** returns new "generic" arrays. + +
+ + + +
+ +## Notes + +- If a `mask` array element is truthy, the corresponding elements in the input arrays are **included** in the respective output arrays; otherwise, the corresponding elements in the input arrays are "masked" and thus **excluded** from the respective output arrays. + +
+ + + +
+ +## Examples + + + +```javascript +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var bernoulli = require( '@stdlib/random/array/bernoulli' ); +var mskfiltern = require( '@stdlib/array/base/mskfiltern' ); + +// Generate linearly spaced arrays: +var x = zeroTo( 20 ); +console.log( x ); + +var y = zeroTo( x.length ); +console.log( y ); + +// Generate a random mask: +var mask = bernoulli( x.length, 0.5, { + 'dtype': 'generic' +}); +console.log( mask ); + +// Filter both arrays using the mask: +var out = mskfiltern( x, y, mask ); +console.log( out ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/mskfiltern/benchmark/benchmark.js new file mode 100644 index 000000000000..a2f993868ec0 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/benchmark/benchmark.js @@ -0,0 +1,55 @@ +/** +* @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 isArrayArray = require( '@stdlib/assert/is-array-array' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var ones = require( '@stdlib/array/base/ones' ); +var pkg = require( './../package.json' ).name; +var mskfiltern = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::copy:num_arrays=2,len=100', function benchmark( b ) { + var x; + var y; + var i; + var v; + + x = zeroTo( 100 ); + y = ones( x.length ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = mskfiltern( x, x, y ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isArrayArray( v ) ) { + b.fail( 'should return an array of arrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/mskfiltern/benchmark/benchmark.length.js new file mode 100644 index 000000000000..b0c53e10b5ee --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/benchmark/benchmark.length.js @@ -0,0 +1,97 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var ones = require( '@stdlib/array/base/ones' ); +var isArrayArray = require( '@stdlib/assert/is-array-array' ); +var pkg = require( './../package.json' ).name; +var mskfiltern = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var x = zeroTo( len ); + var y = ones( len ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var v; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = mskfiltern( x, x, y ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isArrayArray( v ) ) { + b.fail( 'should return an array of arrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':num_arrays=2,len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/docs/repl.txt b/lib/node_modules/@stdlib/array/base/mskfiltern/docs/repl.txt new file mode 100644 index 000000000000..f5d52bc17bcd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/docs/repl.txt @@ -0,0 +1,36 @@ + +{{alias}}( x[, ...arrays], mask ) + Returns new arrays by applying a mask to one or more provided input arrays + in a single pass. + + If a mask array element is truthy, the corresponding elements in the input + arrays are included in the respective output arrays; otherwise, the + corresponding elements in the input arrays are "masked" and thus excluded + from the output arrays. + + Parameters + ---------- + x: ArrayLikeObject + First input array. + + arrays: ...ArrayLikeObject (optional) + Additional input arrays. + + mask: ArrayLikeObject + Mask array. + + Returns + ------- + out: Array + Output arrays. + + Examples + -------- + > var x = [ 1, 2, 3, 4 ]; + > var y = [ 0, 1, 2, 3 ]; + > var out = {{alias}}( x, y, [ 0, 1, 0, 1 ] ) + [ [ 2, 4 ], [ 1, 3 ] ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/mskfiltern/docs/types/index.d.ts new file mode 100644 index 000000000000..76527347767f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/docs/types/index.d.ts @@ -0,0 +1,146 @@ +/* +* @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 + +/// + +import { Collection } from '@stdlib/types/array'; + +/** +* Returns new arrays by applying a mask to a provided input array in a single pass. +* +* @param x - first input array +* @param mask - mask array +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, mask ); +* // returns [ [ 2, 4 ] ] +*/ +declare function mskfiltern( x: Collection, mask: Collection ): [ Array ]; + +/** +* Returns new arrays by applying a mask to two provided input arrays in a single pass. +* +* @param x - first input array +* @param y - second input array +* @param mask - mask array +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ +declare function mskfiltern( x: Collection, y: Collection, mask: Collection ): [ Array, Array ]; + +/** +* Returns new arrays by applying a mask to three provided input arrays in a single pass. +* +* @param x - first input array +* @param y - second input array +* @param z - third input array +* @param mask - mask array +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var z = [ 1, 1, 1, 1 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, z, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ], [ 1, 1 ] ] +*/ +declare function mskfiltern( x: Collection, y: Collection, z: Collection, mask: Collection ): [ Array, Array, Array ]; + +/** +* Returns new arrays by applying a mask to four provided input arrays in a single pass. +* +* @param x - first input array +* @param y - second input array +* @param z - third input array +* @param u - fourth input array +* @param mask - mask array +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var z = [ 1, 1, 1, 1 ]; +* var u = [ 0, 0, 0, 0 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, z, u, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ], [ 1, 1 ], [ 0, 0 ] ] +*/ +declare function mskfiltern( x: Collection, y: Collection, z: Collection, u: Collection, mask: Collection ): [ Array, Array, Array, Array ]; + +/** +* Returns new arrays by applying a mask to five provided input arrays in a single pass. +* +* @param x - first input array +* @param y - second input array +* @param z - third input array +* @param u - fourth input array +* @param v - fifth input array +* @param mask - mask array +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var z = [ 1, 1, 1, 1 ]; +* var u = [ 0, 0, 0, 0 ]; +* var v = [ 1, 2, 3, 4 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, z, u, v, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ], [ 1, 1 ], [ 0, 0 ], [ 2, 4 ] ] +*/ +declare function mskfiltern( x: Collection, y: Collection, z: Collection, u: Collection, v: Collection, mask: Collection ): [ Array, Array, Array, Array, Array ]; + +/** +* Returns new arrays by applying a mask to one or more provided input arrays in a single pass. +* +* @param x - first input array +* @param y - second input array (or mask) +* @param arrays - additional input arrays and mask +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ +declare function mskfiltern( x: Collection, y: Collection, ...arrays: Array ): Array>; + + +// EXPORTS // + +export = mskfiltern; diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/mskfiltern/docs/types/test.ts new file mode 100644 index 000000000000..2a4553c9edba --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/docs/types/test.ts @@ -0,0 +1,61 @@ +/* +* @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. +*/ + +import mskfiltern = require( './index' ); + + +// TESTS // + +// The function returns one or more arrays... +{ + mskfiltern( [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[]] + mskfiltern( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[]] + mskfiltern( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[], number[]] + mskfiltern( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[], number[], number[]] + mskfiltern( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[], number[], number[], number[]] + + mskfiltern( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [any[], any[]] + mskfiltern( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectType [number[], number[]] + mskfiltern( [ '1', '2', '3', '4' ], [ '1', '2', '3', '4' ], [ 0, 0 ] ); // $ExpectType [string[], string[]] +} + +// The compiler throws an error if the function is provided a first argument which is not an array-like object... +{ + mskfiltern( 1, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfiltern( true, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfiltern( false, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfiltern( null, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfiltern( void 0, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError + mskfiltern( {}, [ 1, 2, 3, 4 ], [ 0, 0 ] ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not an array-like object... +{ + mskfiltern( [ 1, 2, 3, 4 ], 1, [ 0, 0 ] ); // $ExpectError + mskfiltern( [ 1, 2, 3, 4 ], true, [ 0, 0 ] ); // $ExpectError + mskfiltern( [ 1, 2, 3, 4 ], false, [ 0, 0 ] ); // $ExpectError + mskfiltern( [ 1, 2, 3, 4 ], null, [ 0, 0 ] ); // $ExpectError + mskfiltern( [ 1, 2, 3, 4 ], void 0, [ 0, 0 ] ); // $ExpectError + mskfiltern( [ 1, 2, 3, 4 ], {}, [ 0, 0 ] ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + mskfiltern(); // $ExpectError + mskfiltern( [] ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/examples/index.js b/lib/node_modules/@stdlib/array/base/mskfiltern/examples/index.js new file mode 100644 index 000000000000..596acf8dc6e5 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/examples/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var bernoulli = require( '@stdlib/random/array/bernoulli' ); +var mskfiltern = require( './../lib' ); + +// Generate linearly spaced arrays: +var x = zeroTo( 20 ); +console.log( x ); + +var y = zeroTo( x.length ); +console.log( y ); + +// Generate a random mask: +var mask = bernoulli( x.length, 0.5, { + 'dtype': 'generic' +}); +console.log( mask ); + +// Filter both arrays using the mask: +var out = mskfiltern( x, y, mask ); +console.log( out ); diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/lib/index.js b/lib/node_modules/@stdlib/array/base/mskfiltern/lib/index.js new file mode 100644 index 000000000000..94a5399dcd31 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/lib/index.js @@ -0,0 +1,44 @@ +/** +* @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'; + +/** +* Apply a mask to one or more provided input arrays in a single pass. +* +* @module @stdlib/array/base/mskfiltern +* +* @example +* var mskfiltern = require( '@stdlib/array/base/mskfiltern' ); +* +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/lib/main.js b/lib/node_modules/@stdlib/array/base/mskfiltern/lib/main.js new file mode 100644 index 000000000000..f6931f32979e --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/lib/main.js @@ -0,0 +1,84 @@ +/** +* @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 resolveGetter = require( '@stdlib/array/base/resolve-getter' ); + + +// MAIN // + +/** +* Returns new arrays by applying a mask to one or more provided input arrays in a single pass. +* +* @param {Collection} x - first input array +* @param {Collection} [...arrays] - additional input arrays +* @param {Collection} mask - mask array +* @returns {Array} output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var mask = [ 0, 1, 0, 1 ]; +* +* var out = mskfiltern( x, y, mask ); +* // returns [ [ 2, 4 ], [ 6, 8 ] ] +*/ +function mskfiltern() { + var getters; + var arrays; + var nargs; + var mget; + var mask; + var out; + var i; + var j; + + nargs = arguments.length; + nargs -= 1; + + // Resolve the mask array and its associated accessor: + mask = arguments[ nargs ]; + mget = resolveGetter( mask ); + + // Resolve accessors for retrieving array elements and initialize the output arrays... + getters = []; + arrays = []; + out = []; + for ( i = 0; i < nargs; i++ ) { + arrays.push( arguments[ i ] ); + getters.push( resolveGetter( arrays[ i ] ) ); + out.push( [] ); + } + // Extract each desired element from the provided arrays... + for ( i = 0; i < mask.length; i++ ) { + if ( mget( mask, i ) ) { + for ( j = 0; j < nargs; j++ ) { + out[ j ].push( getters[ j ]( arrays[ j ], i ) ); // use `Array#push` to ensure "fast" elements + } + } + } + return out; +} + + +// EXPORTS // + +module.exports = mskfiltern; diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/package.json b/lib/node_modules/@stdlib/array/base/mskfiltern/package.json new file mode 100644 index 000000000000..e6a7666b648e --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/package.json @@ -0,0 +1,65 @@ +{ + "name": "@stdlib/array/base/mskfiltern", + "version": "0.0.0", + "description": "Apply a mask to one or more provided input arrays in a single pass.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "utilities", + "utils", + "generic", + "array", + "take", + "extract", + "copy", + "index", + "mask", + "filter", + "reject" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/test/test.js b/lib/node_modules/@stdlib/array/base/mskfiltern/test/test.js new file mode 100644 index 000000000000..dc1236c6e23b --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/test/test.js @@ -0,0 +1,33 @@ +/** +* @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 tape = require( 'tape' ); +var mskfiltern = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof mskfiltern, 'function', 'main export is a function' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/mskfiltern/test/test.main.js b/lib/node_modules/@stdlib/array/base/mskfiltern/test/test.main.js new file mode 100644 index 000000000000..4ca97c4da187 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/mskfiltern/test/test.main.js @@ -0,0 +1,257 @@ +/** +* @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 tape = require( 'tape' ); +var Complex64Array = require( '@stdlib/array/complex64' ); +var BooleanArray = require( '@stdlib/array/bool' ); +var isSameComplex64 = require( '@stdlib/assert/is-same-complex64' ); +var isArray = require( '@stdlib/assert/is-array' ); +var mskfiltern = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof mskfiltern, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function filters array elements (1 array)', function test( t ) { + var expected; + var actual; + var mask; + var x; + + x = [ 1, 2, 3, 4 ]; + + mask = [ 0, 1, 0, 1 ]; + actual = mskfiltern( x, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 1, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + + expected = [ 2, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + mask = [ 0, 0, 0, 0 ]; + actual = mskfiltern( x, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 1, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + + expected = []; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + mask = [ 0, 0, 0, 1 ]; + actual = mskfiltern( x, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 1, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + + expected = [ 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + mask = [ 1, 1, 1, 1 ]; + actual = mskfiltern( x, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 1, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + + expected = [ 1, 2, 3, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function filters array elements (2 arrays)', function test( t ) { + var expected; + var actual; + var mask; + var y; + var x; + + x = [ 1, 2, 3, 4 ]; + y = [ 0, 1, 2, 3 ]; + + mask = [ 0, 1, 0, 1 ]; + actual = mskfiltern( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ 2, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 1, 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + mask = [ 0, 0, 0, 0 ]; + actual = mskfiltern( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = []; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = []; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + mask = [ 0, 0, 0, 1 ]; + actual = mskfiltern( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + mask = [ 1, 1, 1, 1 ]; + actual = mskfiltern( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ 1, 2, 3, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 0, 1, 2, 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function filters array elements (3 arrays)', function test( t ) { + var expected; + var actual; + var mask; + var x; + var y; + var z; + + x = [ 1, 2, 3, 4 ]; + y = [ 0, 1, 2, 3 ]; + z = [ 5, 6, 7, 8 ]; + + mask = [ 0, 1, 0, 1 ]; + actual = mskfiltern( x, y, z, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 3, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 2 ] ), true, 'returns expected value' ); + + expected = [ 2, 4 ]; + t.notEqual( actual[ 0 ], x, 'returns expected value' ); + t.deepEqual( actual[ 0 ], expected, 'returns expected value' ); + + expected = [ 1, 3 ]; + t.notEqual( actual[ 1 ], y, 'returns expected value' ); + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + expected = [ 6, 8 ]; + t.notEqual( actual[ 2 ], z, 'returns expected value' ); + t.deepEqual( actual[ 2 ], expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function filters array elements (2 arrays; accessors)', function test( t ) { + var expected; + var actual; + var mask; + var y; + var x; + var i; + + x = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + y = [ 0, 1, 2, 3 ]; + mask = [ 0, 1, 0, 1 ]; + actual = mskfiltern( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ x.get( 1 ), x.get( 3 ) ]; + for ( i = 0; i < expected.length; i++ ) { + t.strictEqual( isSameComplex64( actual[ 0 ][ i ], expected[ i ] ), true, 'returns expected value' ); + } + expected = [ 1, 3 ]; + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + x = new BooleanArray( [ true, false, false, true ] ); + y = [ 0, 1, 2, 3 ]; + mask = [ 0, 1, 0, 1 ]; + actual = mskfiltern( x, y, mask ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.strictEqual( actual.length, 2, 'returns expected value' ); + t.strictEqual( isArray( actual[ 0 ] ), true, 'returns expected value' ); + t.strictEqual( isArray( actual[ 1 ] ), true, 'returns expected value' ); + + expected = [ x.get( 1 ), x.get( 3 ) ]; + for ( i = 0; i < expected.length; i++ ) { + t.strictEqual( actual[ 0 ][ i ], expected[ i ], 'returns expected value' ); + } + expected = [ 1, 3 ]; + t.deepEqual( actual[ 1 ], expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns empty arrays if provided empty arrays', function test( t ) { + t.deepEqual( mskfiltern( [], [] ), [ [] ], 'returns expected value' ); + t.deepEqual( mskfiltern( [], [], [] ), [ [], [] ], 'returns expected value' ); + t.deepEqual( mskfiltern( [], [], [], [] ), [ [], [], [] ], 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/mskreject/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/mskreject/docs/types/test.ts index af46bf6080a0..dc6498141977 100644 --- a/lib/node_modules/@stdlib/array/base/mskreject/docs/types/test.ts +++ b/lib/node_modules/@stdlib/array/base/mskreject/docs/types/test.ts @@ -39,7 +39,7 @@ import mskreject = require( './index' ); mskreject( {}, [ 0, 0 ] ); // $ExpectError } -// The compiler throws an error if the function is provided a second argument which is not an array-like object containing numbers... +// The compiler throws an error if the function is provided a second argument which is not an array-like object... { mskreject( [], 1 ); // $ExpectError mskreject( [], true ); // $ExpectError diff --git a/lib/node_modules/@stdlib/array/base/ones/README.md b/lib/node_modules/@stdlib/array/base/ones/README.md index 1fd7cb3eea27..be21bf154635 100644 --- a/lib/node_modules/@stdlib/array/base/ones/README.md +++ b/lib/node_modules/@stdlib/array/base/ones/README.md @@ -103,6 +103,17 @@ console.log( arr ); @@ -111,6 +122,22 @@ console.log( arr ); diff --git a/lib/node_modules/@stdlib/array/base/ones4d/README.md b/lib/node_modules/@stdlib/array/base/ones4d/README.md index 6c9020181acf..9a5cc12705d3 100644 --- a/lib/node_modules/@stdlib/array/base/ones4d/README.md +++ b/lib/node_modules/@stdlib/array/base/ones4d/README.md @@ -95,6 +95,17 @@ out = ones4d( [ 1, 1, 3, 1 ] ); @@ -103,6 +114,22 @@ out = ones4d( [ 1, 1, 3, 1 ] ); diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/README.md b/lib/node_modules/@stdlib/array/base/scatter-filled/README.md new file mode 100644 index 000000000000..10320768224c --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/README.md @@ -0,0 +1,121 @@ + + +# scatterFilled + +> Scatter a list of provided values to specified indices in a new filled "generic" array. + +
+ +## Usage + +```javascript +var scatterFilled = require( '@stdlib/array/base/scatter-filled' ); +``` + +#### scatterFilled( fill, len, indices, values, mode ) + +Scatters a list of provided values to specified indices in a new filled "generic" array. + +```javascript +var out = scatterFilled( null, 4, [ 1, 3 ], [ 20, 40 ], 'throw' ); +// returns [ null, 20, null, 40 ] +``` + +The function supports the following parameters: + +- **fill**: fill value. +- **len**: output array length. +- **indices**: list of indices. +- **values**: values to scatter. When `indices` contains one or more elements, `values` must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with `indices` (i.e., must have either one element or the same number of elements as `indices`). +- **mode**: index [mode][@stdlib/ndarray/base/ind]. + +If `indices` is an empty array, the function returns a filled array. + +```javascript +var out = scatterFilled( null, 4, [], [ 20, 40 ], 'throw' ); +// returns [ null, null, null, null ] +``` + +The function supports broadcasting a `values` array containing a single element against an `indices` array containing one or more elements. + +```javascript +var out = scatterFilled( null, 4, [ 1, 3 ], [ 20 ], 'throw' ); +// returns [ null, 20, null, 20 ] +``` + +
+ + + +
+ +
+ + + +
+ +## Examples + + + +```javascript +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var scatterFilled = require( '@stdlib/array/base/scatter-filled' ); + +// Generate an array of random indices: +var N = discreteUniform( 5, 15 ); +var indices = filledBy( N, discreteUniform.factory( 0, 10 ) ); +console.log( indices ); + +// Generate an array of random values: +var values = filledBy( N, discreteUniform.factory( 1000, 2025 ) ); +console.log( values ); + +// Scatter a random sample of elements to a new array: +var out = scatterFilled( null, 11, indices, values, 'throw' ); +console.log( out ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/scatter-filled/benchmark/benchmark.js new file mode 100644 index 000000000000..bf9906654373 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/benchmark/benchmark.js @@ -0,0 +1,76 @@ +/** +* @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 zeroTo = require( '@stdlib/array/base/zero-to' ); +var pkg = require( './../package.json' ).name; +var scatterFilled = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::no_broadcasting:len=100', function benchmark( b ) { + var idx; + var x; + var i; + var v; + + x = zeroTo( 100 ); + idx = zeroTo( 100 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = scatterFilled( -1, x.length, idx, x, 'throw' ); + 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(); +}); + +bench( pkg+'::broadcasting:len=100', function benchmark( b ) { + var idx; + var i; + var v; + + idx = zeroTo( 100 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = scatterFilled( -1, 100, idx, [ i ], 'throw' ); + 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(); +}); diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/scatter-filled/benchmark/benchmark.length.js new file mode 100644 index 000000000000..8eb15d4771d0 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/benchmark/benchmark.length.js @@ -0,0 +1,111 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var isArray = require( '@stdlib/assert/is-array' ); +var pkg = require( './../package.json' ).name; +var scatterFilled = require( './../lib' ); + + +// VARIABLES // + +var opts = { + 'dtype': 'generic' +}; + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var values; + var idx; + + idx = zeroTo( len ); + values = [ + discreteUniform( len, -10, 0, opts ), + discreteUniform( len, 0, 10, opts ) + ]; + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var v; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = scatterFilled( -999, len, idx, values[ i%values.length ], 'throw' ); + 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(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/docs/repl.txt b/lib/node_modules/@stdlib/array/base/scatter-filled/docs/repl.txt new file mode 100644 index 000000000000..fc95f32cc160 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/docs/repl.txt @@ -0,0 +1,48 @@ + +{{alias}}( fill, len, indices, values, mode ) + Scatters a list of provided values to specified indices in a new filled + "generic" array. + + The function supports broadcasting a `values` array containing a single + element against an `indices` array containing one or more elements. + + If `indices` is an empty array, the function returns a filled array. + + Parameters + ---------- + fill: any + Fill value. + + len: integer + Output array length. + + indices: ArrayLikeObject + List of element indices. + + values: ArrayLikeObject + Values to scatter. When `indices` contains one or more elements, + `values` must be broadcast compatible with `indices` (i.e., must have + either one element or the same number of elements as `indices`). + + mode: string + Specifies how to handle an index outside the interval [0, max], where + `max` is the maximum possible array index. If equal to 'throw', the + function throws an error. If equal to 'normalize', the function throws + an error if provided an out-of-bounds normalized index. If equal to + 'wrap', the function wraps around an index using modulo arithmetic. If + equal to 'clamp', the function sets an index to either 0 (minimum index) + or the maximum index. + + Returns + ------- + out: Array + Output array. + + Examples + -------- + > var out = {{alias}}( null, 4, [ 1, 3 ], [ 20, 40 ], 'throw' ) + [ null, 20, null, 40 ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/scatter-filled/docs/types/index.d.ts new file mode 100644 index 000000000000..f6d9d77e952d --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/docs/types/index.d.ts @@ -0,0 +1,62 @@ +/* +* @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 + +/// + +import { Collection, AccessorArrayLike } from '@stdlib/types/array'; +import { Mode } from '@stdlib/types/ndarray'; + +/** +* Index array. +*/ +type IndexArray = Collection | AccessorArrayLike; + +/** +* Values array. +*/ +type ValuesArray = Collection | AccessorArrayLike; + +/** +* Scatters a list of provided values to specified indices in a new filled "generic" array. +* +* @param fill - fill value +* @param len - output array length +* @param indices - list of element indices +* @param values - values to scatter +* @param mode - index mode +* @returns output array +* +* @example +* var indices = [ 1, 2 ]; +* var values = [ 20, 30 ]; +* +* var out = scatterFilled( null, 4, indices, values, 'throw' ); +* // returns [ null, 20, 30, null ] +* +* @example +* var out = scatterFilled( null, 4, [ 1, 2 ], [ 30 ], 'throw' ); +* // returns [ null, 30, 30, null ] +*/ +declare function scatterFilled( fill: T, len: number, indices: IndexArray, values: ValuesArray, mode: Mode ): Array; + + +// EXPORTS // + +export = scatterFilled; diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/scatter-filled/docs/types/test.ts new file mode 100644 index 000000000000..b9a135a86a01 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/docs/types/test.ts @@ -0,0 +1,92 @@ +/* +* @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. +*/ + +import Complex128 = require( '@stdlib/complex/float64/ctor' ); +import AccessorArray = require( '@stdlib/array/base/accessor' ); +import scatterFilled = require( './index' ); + + +// TESTS // + +// The function returns an array... +{ + const z = new Complex128( 3.0, 4.0 ); + + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectType (number | null)[] + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], 'clamp' ); // $ExpectType (number | null)[] + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], 'wrap' ); // $ExpectType (number | null)[] + scatterFilled( null, 4, [ 1, 3 ], [ true, true ], 'normalize' ); // $ExpectType (boolean | null)[] + + scatterFilled( null, 4, [ 1, 3 ], [ z, z ], 'throw' ); // $ExpectType (Complex128 | null)[] + scatterFilled( null, 4, [ 1, 3 ], [ z, z ], 'throw' ); // $ExpectType (Complex128 | null)[] + scatterFilled( null, 4, [ 1, 3 ], new AccessorArray( [ 20, 30 ] ), 'throw' ); // $ExpectType (number | null)[] +} + +// The compiler throws an error if the function is provided a second argument which is not a number... +{ + scatterFilled( null, '1', [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, true, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, false, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, null, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, void 0, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, [], [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, {}, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not an array-like object containing numbers... +{ + scatterFilled( null, 4, 1, [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, 4, true, [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, 4, false, [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, 4, null, [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, 4, void 0, [ 20, 30 ], 'throw' ); // $ExpectError + scatterFilled( null, 4, {}, [ 20, 30 ], 'throw' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not an array-like object... +{ + scatterFilled( null, 4, [ 1, 3 ], 1, 'throw' ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], true, 'throw' ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], false, 'throw' ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], null, 'throw' ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], void 0, 'throw' ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], {}, 'throw' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fifth argument which is not a valid index mode... +{ + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], '1' ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], 1 ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], true ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], false ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], null ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], void 0 ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], {} ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], [] ); // $ExpectError + scatterFilled( null, 4, [ 1, 3 ], [ 20, 30 ], ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + scatterFilled(); // $ExpectError + scatterFilled( null ); // $ExpectError + scatterFilled( null, 4 ); // $ExpectError + scatterFilled( null, 4, [] ); // $ExpectError + scatterFilled( null, 4, [], [] ); // $ExpectError + scatterFilled( null, 4, [], [], 'throw', {} ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/examples/index.js b/lib/node_modules/@stdlib/array/base/scatter-filled/examples/index.js new file mode 100644 index 000000000000..03dd776085e1 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/examples/index.js @@ -0,0 +1,36 @@ +/** +* @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'; + +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var scatterFilled = require( './../lib' ); + +// Generate an array of random indices: +var N = discreteUniform( 5, 15 ); +var indices = filledBy( N, discreteUniform.factory( 0, 10 ) ); +console.log( indices ); + +// Generate an array of random values: +var values = filledBy( N, discreteUniform.factory( 1000, 2025 ) ); +console.log( values ); + +// Scatter a random sample of elements to a new array: +var out = scatterFilled( null, 11, indices, values, 'throw' ); +console.log( out ); diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/lib/index.js b/lib/node_modules/@stdlib/array/base/scatter-filled/lib/index.js new file mode 100644 index 000000000000..dc54ffcefa0d --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/lib/index.js @@ -0,0 +1,43 @@ +/** +* @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'; + +/** +* Scatter a list of provided values to specified indices in a new filled "generic" array. +* +* @module @stdlib/array/base/scatter-filled +* +* @example +* var scatterFilled = require( '@stdlib/array/base/scatter-filled' ); +* +* var indices = [ 1, 2 ]; +* var values = [ 20, 30 ]; +* +* var out = scatterFilled( null, 4, indices, values, 'throw' ); +* // returns [ null, 20, 30, null ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/lib/main.js b/lib/node_modules/@stdlib/array/base/scatter-filled/lib/main.js new file mode 100644 index 000000000000..4de51bed2c2a --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/lib/main.js @@ -0,0 +1,61 @@ +/** +* @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 filled = require( '@stdlib/array/base/filled' ); +var put = require( '@stdlib/array/base/put' ); + + +// MAIN // + +/** +* Scatters a list of provided values to specified indices in a new filled "generic" array. +* +* @param {*} fill - fill value +* @param {NonNegativeInteger} len - output array length +* @param {IntegerArray} indices - list of indices +* @param {Collection} values - values to scatter +* @param {string} mode - index mode +* @throws {Error} third argument must be broadcast compatible with the second argument +* @returns {Array} output array +* +* @example +* var indices = [ 1, 2 ]; +* var values = [ 20, 30 ]; +* +* var out = scatterFilled( null, 4, indices, values, 'throw' ); +* // returns [ null, 20, 30, null ] +* +* @example +* var indices = [ 1, 2 ]; +* var values = [ 30 ]; +* +* var out = scatterFilled( null, 4, indices, values, 'throw' ); +* // returns [ null, 30, 30, null ] +*/ +function scatterFilled( fill, len, indices, values, mode ) { + return put( filled( fill, len ), indices, values, mode ); +} + + +// EXPORTS // + +module.exports = scatterFilled; diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/package.json b/lib/node_modules/@stdlib/array/base/scatter-filled/package.json new file mode 100644 index 000000000000..21fbd5e27fd9 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/package.json @@ -0,0 +1,62 @@ +{ + "name": "@stdlib/array/base/scatter-filled", + "version": "0.0.0", + "description": "Scatter a list of provided values to specified indices in a new filled \"generic\" array.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "utilities", + "utils", + "generic", + "array", + "set", + "scatter", + "filled", + "fill" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/scatter-filled/test/test.js b/lib/node_modules/@stdlib/array/base/scatter-filled/test/test.js new file mode 100644 index 000000000000..4de7827ed4fd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scatter-filled/test/test.js @@ -0,0 +1,203 @@ +/** +* @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 tape = require( 'tape' ); +var isArray = require( '@stdlib/assert/is-array' ); +var scatterFilled = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof scatterFilled, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function throws an error if provided a fourth argument which is not broadcast compatible with the second argument', function test( t ) { + var values; + var i; + + values = [ + [], + [ 1, 2, 3 ], + [ 1, 2, 3, 4 ], + [ 1, 2, 3, 4, 5 ] + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), Error, 'throws an error when provided an array of length ' + values[ i ].length ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + scatterFilled( null, 4, [ 1, 2 ], value, 'throw' ); + }; + } +}); + +tape( 'the function scatters elements to a new array', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ 1, 3 ]; + actual = scatterFilled( null, 4, indices, [ 20, 40 ], 'throw' ); + expected = [ null, 20, null, 40 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 3, 3 ]; + actual = scatterFilled( null, 4, indices, [ 20, 30, 40, 50 ], 'throw' ); + expected = [ null, 30, null, 50 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 3, 2, 1, 0 ]; + actual = scatterFilled( null, 4, indices, [ 20, 30, 40, 50 ], 'throw' ); + expected = [ 50, 40, 30, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]; + actual = scatterFilled( null, 4, indices, [ 100, 100, 100, 100, 100, 100, 100, 100, 100, 100 ], 'throw' ); + expected = [ null, 100, null, null ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function scatters elements to a new array (broadcasting)', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ 1, 3 ]; + actual = scatterFilled( null, 4, indices, [ 20 ], 'throw' ); + expected = [ null, 20, null, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 3, 3 ]; + actual = scatterFilled( null, 4, indices, [ 20 ], 'throw' ); + expected = [ null, 20, null, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 3, 2, 1, 0 ]; + actual = scatterFilled( null, 4, indices, [ 20 ], 'throw' ); + expected = [ 20, 20, 20, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]; + actual = scatterFilled( null, 4, indices, [ 100 ], 'throw' ); + expected = [ null, 100, null, null ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns a filled array if provided a second argument which is empty', function test( t ) { + var actual; + + actual = scatterFilled( null, 4, [], [ 5, 6, 7, 8 ], 'throw' ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, [ null, null, null, null ], 'returns expected value' ); + + t.end(); +}); + +tape( 'when the "mode" is "throw", the function throws an error if provided an out-of-bounds index', function test( t ) { + var indices; + + indices = [ 4, 5, 1, 2 ]; + + t.throws( badValue, RangeError, 'throws an error' ); + t.end(); + + function badValue() { + scatterFilled( null, 4, indices, [ 200 ], 'throw' ); + } +}); + +tape( 'when the "mode" is "normalize", the function normalizes negative indices', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ -1, -2, -3, -4 ]; + actual = scatterFilled( null, 4, indices, [ 5, 6, 7, 8 ], 'normalize' ); + expected = [ 8, 7, 6, 5 ]; + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'when the "mode" is "normalize", the function throws an error if provided an out-of-bounds index', function test( t ) { + var indices; + + indices = [ 2, 50, 1, 2 ]; + + t.throws( badValue, RangeError, 'throws an error' ); + t.end(); + + function badValue() { + scatterFilled( null, 4, indices, [ 100 ], 'normalize' ); + } +}); + +tape( 'when the "mode" is "clamp", the function clamps out-of-bounds indices', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ -10, 10, -5, 5 ]; + actual = scatterFilled( null, 4, indices, [ 100, 200, 300, 400 ], 'clamp' ); + expected = [ 300, null, null, 400 ]; + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'when the "mode" is "wrap", the function wraps out-of-bounds indices', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ -10, 10, -5, 5 ]; + actual = scatterFilled( null, 4, indices, [ 100, 200, 300, 400 ], 'wrap' ); + expected = [ null, 400, 200, 300 ]; + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/scattered/README.md b/lib/node_modules/@stdlib/array/base/scattered/README.md new file mode 100644 index 000000000000..73d289de1498 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/README.md @@ -0,0 +1,120 @@ + + +# scattered + +> Scatter a list of provided values to specified indices in a new zero-filled "generic" array. + +
+ +## Usage + +```javascript +var scattered = require( '@stdlib/array/base/scattered' ); +``` + +#### scattered( len, indices, values, mode ) + +Scatters a list of provided values to specified indices in a new zero-filled "generic" array. + +```javascript +var out = scattered( 4, [ 1, 3 ], [ 20, 40 ], 'throw' ); +// returns [ 0, 20, 0, 40 ] +``` + +The function supports the following parameters: + +- **len**: output array length. +- **indices**: list of indices. +- **values**: values to scatter. When `indices` contains one or more elements, `values` must be broadcast [compatible][@stdlib/ndarray/base/broadcast-shapes] with `indices` (i.e., must have either one element or the same number of elements as `indices`). +- **mode**: index [mode][@stdlib/ndarray/base/ind]. + +If `indices` is an empty array, the function returns a zero-filled array. + +```javascript +var out = scattered( 4, [], [ 20, 40 ], 'throw' ); +// returns [ 0, 0, 0, 0 ] +``` + +The function supports broadcasting a `values` array containing a single element against an `indices` array containing one or more elements. + +```javascript +var out = scattered( 4, [ 1, 3 ], [ 20 ], 'throw' ); +// returns [ 0, 20, 0, 20 ] +``` + +
+ + + +
+ +
+ + + +
+ +## Examples + + + +```javascript +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var scattered = require( '@stdlib/array/base/scattered' ); + +// Generate an array of random indices: +var N = discreteUniform( 5, 15 ); +var indices = filledBy( N, discreteUniform.factory( 0, 10 ) ); +console.log( indices ); + +// Generate an array of random values: +var values = filledBy( N, discreteUniform.factory( 1000, 2025 ) ); +console.log( values ); + +// Scatter a random sample of elements to a new array: +var out = scattered( 11, indices, values, 'throw' ); +console.log( out ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/scattered/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/scattered/benchmark/benchmark.js new file mode 100644 index 000000000000..41120235e615 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/benchmark/benchmark.js @@ -0,0 +1,76 @@ +/** +* @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 zeroTo = require( '@stdlib/array/base/zero-to' ); +var pkg = require( './../package.json' ).name; +var scattered = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::no_broadcasting:len=100', function benchmark( b ) { + var idx; + var x; + var i; + var v; + + x = zeroTo( 100 ); + idx = zeroTo( 100 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = scattered( x.length, idx, x, 'throw' ); + 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(); +}); + +bench( pkg+'::broadcasting:len=100', function benchmark( b ) { + var idx; + var i; + var v; + + idx = zeroTo( 100 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = scattered( 100, idx, [ i ], 'throw' ); + 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(); +}); diff --git a/lib/node_modules/@stdlib/array/base/scattered/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/scattered/benchmark/benchmark.length.js new file mode 100644 index 000000000000..4294a447eef3 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/benchmark/benchmark.length.js @@ -0,0 +1,111 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var isArray = require( '@stdlib/assert/is-array' ); +var pkg = require( './../package.json' ).name; +var scattered = require( './../lib' ); + + +// VARIABLES // + +var opts = { + 'dtype': 'generic' +}; + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var values; + var idx; + + idx = zeroTo( len ); + values = [ + discreteUniform( len, -10, 0, opts ), + discreteUniform( len, 0, 10, opts ) + ]; + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var v; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = scattered( len, idx, values[ i%values.length ], 'throw' ); + 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(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/scattered/docs/repl.txt b/lib/node_modules/@stdlib/array/base/scattered/docs/repl.txt new file mode 100644 index 000000000000..06be220cf66b --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/docs/repl.txt @@ -0,0 +1,45 @@ + +{{alias}}( len, indices, values, mode ) + Scatters a list of provided values to specified indices in a new zero-filled + "generic" array. + + The function supports broadcasting a `values` array containing a single + element against an `indices` array containing one or more elements. + + If `indices` is an empty array, the function returns a zero-filled array. + + Parameters + ---------- + len: integer + Output array length. + + indices: ArrayLikeObject + List of element indices. + + values: ArrayLikeObject + Values to scatter. When `indices` contains one or more elements, + `values` must be broadcast compatible with `indices` (i.e., must have + either one element or the same number of elements as `indices`). + + mode: string + Specifies how to handle an index outside the interval [0, max], where + `max` is the maximum possible array index. If equal to 'throw', the + function throws an error. If equal to 'normalize', the function throws + an error if provided an out-of-bounds normalized index. If equal to + 'wrap', the function wraps around an index using modulo arithmetic. If + equal to 'clamp', the function sets an index to either 0 (minimum index) + or the maximum index. + + Returns + ------- + out: Array + Output array. + + Examples + -------- + > var out = {{alias}}( 4, [ 1, 3 ], [ 20, 40 ], 'throw' ) + [ 0, 20, 0, 40 ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/scattered/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/scattered/docs/types/index.d.ts new file mode 100644 index 000000000000..b52a2fe1ee00 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/docs/types/index.d.ts @@ -0,0 +1,61 @@ +/* +* @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 + +/// + +import { Collection, AccessorArrayLike } from '@stdlib/types/array'; +import { Mode } from '@stdlib/types/ndarray'; + +/** +* Index array. +*/ +type IndexArray = Collection | AccessorArrayLike; + +/** +* Values array. +*/ +type ValuesArray = Collection | AccessorArrayLike; + +/** +* Scatters a list of provided values to specified indices in a new zero-filled "generic" array. +* +* @param len - output array length +* @param indices - list of element indices +* @param values - values to scatter +* @param mode - index mode +* @returns output array +* +* @example +* var indices = [ 1, 2 ]; +* var values = [ 20, 30 ]; +* +* var out = scattered( 4, indices, values, 'throw' ); +* // returns [ 0, 20, 30, 0 ] +* +* @example +* var out = scattered( 4, [ 1, 2 ], [ 30 ], 'throw' ); +* // returns [ 0, 30, 30, 0 ] +*/ +declare function scattered( len: number, indices: IndexArray, values: ValuesArray, mode: Mode ): Array; + + +// EXPORTS // + +export = scattered; diff --git a/lib/node_modules/@stdlib/array/base/scattered/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/scattered/docs/types/test.ts new file mode 100644 index 000000000000..c76ed7acd6ff --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/docs/types/test.ts @@ -0,0 +1,92 @@ +/* +* @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. +*/ + +import Complex128 = require( '@stdlib/complex/float64/ctor' ); +import AccessorArray = require( '@stdlib/array/base/accessor' ); +import scattered = require( './index' ); + + +// TESTS // + +// The function returns an array... +{ + const z = new Complex128( 3.0, 4.0 ); + + scattered( 4, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectType number[] + scattered( 4, [ 1, 3 ], [ 20, 30 ], 'clamp' ); // $ExpectType number[] + scattered( 4, [ 1, 3 ], [ 20, 30 ], 'wrap' ); // $ExpectType number[] + scattered( 4, [ 1, 3 ], [ true, true ], 'normalize' ); // $ExpectType (number | boolean)[] + + scattered( 4, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectType number[] + scattered( 4, [ 1, 3 ], [ z, z ], 'throw' ); // $ExpectType (number | Complex128)[] + scattered( 4, [ 1, 3 ], [ z, z ], 'throw' ); // $ExpectType (number | Complex128)[] + scattered( 4, [ 1, 3 ], new AccessorArray( [ 20, 30 ] ), 'throw' ); // $ExpectType number[] +} + +// The compiler throws an error if the function is provided a first argument which is not a number... +{ + scattered( '1', [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scattered( true, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scattered( false, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scattered( null, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scattered( void 0, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scattered( [], [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError + scattered( {}, [ 1, 3 ], [ 20, 30 ], 'throw' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not an array-like object containing numbers... +{ + scattered( 4, 1, [ 20, 30 ], 'throw' ); // $ExpectError + scattered( 4, true, [ 20, 30 ], 'throw' ); // $ExpectError + scattered( 4, false, [ 20, 30 ], 'throw' ); // $ExpectError + scattered( 4, null, [ 20, 30 ], 'throw' ); // $ExpectError + scattered( 4, void 0, [ 20, 30 ], 'throw' ); // $ExpectError + scattered( 4, {}, [ 20, 30 ], 'throw' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not an array-like object... +{ + scattered( 4, [ 1, 3 ], 1, 'throw' ); // $ExpectError + scattered( 4, [ 1, 3 ], true, 'throw' ); // $ExpectError + scattered( 4, [ 1, 3 ], false, 'throw' ); // $ExpectError + scattered( 4, [ 1, 3 ], null, 'throw' ); // $ExpectError + scattered( 4, [ 1, 3 ], void 0, 'throw' ); // $ExpectError + scattered( 4, [ 1, 3 ], {}, 'throw' ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not a valid index mode... +{ + scattered( 4, [ 1, 3 ], [ 20, 30 ], '1' ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], 1 ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], true ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], false ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], null ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], void 0 ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], {} ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], [] ); // $ExpectError + scattered( 4, [ 1, 3 ], [ 20, 30 ], ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + scattered(); // $ExpectError + scattered( 4 ); // $ExpectError + scattered( 4, [] ); // $ExpectError + scattered( 4, [], [] ); // $ExpectError + scattered( 4, [], [], 'throw', {} ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/scattered/examples/index.js b/lib/node_modules/@stdlib/array/base/scattered/examples/index.js new file mode 100644 index 000000000000..d4da4a71accd --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/examples/index.js @@ -0,0 +1,36 @@ +/** +* @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'; + +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var scattered = require( './../lib' ); + +// Generate an array of random indices: +var N = discreteUniform( 5, 15 ); +var indices = filledBy( N, discreteUniform.factory( 0, 10 ) ); +console.log( indices ); + +// Generate an array of random values: +var values = filledBy( N, discreteUniform.factory( 1000, 2025 ) ); +console.log( values ); + +// Scatter a random sample of elements to a new array: +var out = scattered( 11, indices, values, 'throw' ); +console.log( out ); diff --git a/lib/node_modules/@stdlib/array/base/scattered/lib/index.js b/lib/node_modules/@stdlib/array/base/scattered/lib/index.js new file mode 100644 index 000000000000..b6578847298d --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/lib/index.js @@ -0,0 +1,43 @@ +/** +* @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'; + +/** +* Scatter a list of provided values to specified indices in a new zero-filled "generic" array. +* +* @module @stdlib/array/base/scattered +* +* @example +* var scattered = require( '@stdlib/array/base/scattered' ); +* +* var indices = [ 1, 2 ]; +* var values = [ 20, 30 ]; +* +* var out = scattered( 4, indices, values, 'throw' ); +* // returns [ 0, 20, 30, 0 ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/scattered/lib/main.js b/lib/node_modules/@stdlib/array/base/scattered/lib/main.js new file mode 100644 index 000000000000..ca0642bd0c0a --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/lib/main.js @@ -0,0 +1,60 @@ +/** +* @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 zeros = require( '@stdlib/array/base/zeros' ); +var put = require( '@stdlib/array/base/put' ); + + +// MAIN // + +/** +* Scatters a list of provided values to specified indices in a new zero-filled "generic" array. +* +* @param {NonNegativeInteger} len - output array length +* @param {IntegerArray} indices - list of indices +* @param {Collection} values - values to scatter +* @param {string} mode - index mode +* @throws {Error} third argument must be broadcast compatible with the second argument +* @returns {Array} output array +* +* @example +* var indices = [ 1, 2 ]; +* var values = [ 20, 30 ]; +* +* var out = scattered( 4, indices, values, 'throw' ); +* // returns [ 0, 20, 30, 0 ] +* +* @example +* var indices = [ 1, 2 ]; +* var values = [ 30 ]; +* +* var out = scattered( 4, indices, values, 'throw' ); +* // returns [ 0, 30, 30, 0 ] +*/ +function scattered( len, indices, values, mode ) { + return put( zeros( len ), indices, values, mode ); +} + + +// EXPORTS // + +module.exports = scattered; diff --git a/lib/node_modules/@stdlib/array/base/scattered/package.json b/lib/node_modules/@stdlib/array/base/scattered/package.json new file mode 100644 index 000000000000..098221dca365 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/package.json @@ -0,0 +1,62 @@ +{ + "name": "@stdlib/array/base/scattered", + "version": "0.0.0", + "description": "Scatter a list of provided values to specified indices in a new zero-filled \"generic\" array.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "utilities", + "utils", + "generic", + "array", + "set", + "scatter", + "filled", + "fill" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/scattered/test/test.js b/lib/node_modules/@stdlib/array/base/scattered/test/test.js new file mode 100644 index 000000000000..b9a27d3b397a --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/scattered/test/test.js @@ -0,0 +1,203 @@ +/** +* @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 tape = require( 'tape' ); +var isArray = require( '@stdlib/assert/is-array' ); +var scattered = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof scattered, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function throws an error if provided a third argument which is not broadcast compatible with the second argument', function test( t ) { + var values; + var i; + + values = [ + [], + [ 1, 2, 3 ], + [ 1, 2, 3, 4 ], + [ 1, 2, 3, 4, 5 ] + ]; + + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), Error, 'throws an error when provided an array of length ' + values[ i ].length ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + scattered( 4, [ 1, 2 ], value, 'throw' ); + }; + } +}); + +tape( 'the function scatters elements to a new array', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ 1, 3 ]; + actual = scattered( 4, indices, [ 20, 40 ], 'throw' ); + expected = [ 0, 20, 0, 40 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 3, 3 ]; + actual = scattered( 4, indices, [ 20, 30, 40, 50 ], 'throw' ); + expected = [ 0, 30, 0, 50 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 3, 2, 1, 0 ]; + actual = scattered( 4, indices, [ 20, 30, 40, 50 ], 'throw' ); + expected = [ 50, 40, 30, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]; + actual = scattered( 4, indices, [ 100, 100, 100, 100, 100, 100, 100, 100, 100, 100 ], 'throw' ); + expected = [ 0, 100, 0, 0 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function scatters elements to a new array (broadcasting)', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ 1, 3 ]; + actual = scattered( 4, indices, [ 20 ], 'throw' ); + expected = [ 0, 20, 0, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 3, 3 ]; + actual = scattered( 4, indices, [ 20 ], 'throw' ); + expected = [ 0, 20, 0, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 3, 2, 1, 0 ]; + actual = scattered( 4, indices, [ 20 ], 'throw' ); + expected = [ 20, 20, 20, 20 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]; + actual = scattered( 4, indices, [ 100 ], 'throw' ); + expected = [ 0, 100, 0, 0 ]; + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns a zero-filled array if provided a second argument which is empty', function test( t ) { + var actual; + + actual = scattered( 4, [], [ 5, 6, 7, 8 ], 'throw' ); + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, [ 0, 0, 0, 0 ], 'returns expected value' ); + + t.end(); +}); + +tape( 'when the "mode" is "throw", the function throws an error if provided an out-of-bounds index', function test( t ) { + var indices; + + indices = [ 4, 5, 1, 2 ]; + + t.throws( badValue, RangeError, 'throws an error' ); + t.end(); + + function badValue() { + scattered( 4, indices, [ 200 ], 'throw' ); + } +}); + +tape( 'when the "mode" is "normalize", the function normalizes negative indices', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ -1, -2, -3, -4 ]; + actual = scattered( 4, indices, [ 5, 6, 7, 8 ], 'normalize' ); + expected = [ 8, 7, 6, 5 ]; + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'when the "mode" is "normalize", the function throws an error if provided an out-of-bounds index', function test( t ) { + var indices; + + indices = [ 2, 50, 1, 2 ]; + + t.throws( badValue, RangeError, 'throws an error' ); + t.end(); + + function badValue() { + scattered( 4, indices, [ 100 ], 'normalize' ); + } +}); + +tape( 'when the "mode" is "clamp", the function clamps out-of-bounds indices', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ -10, 10, -5, 5 ]; + actual = scattered( 4, indices, [ 100, 200, 300, 400 ], 'clamp' ); + expected = [ 300, 0, 0, 400 ]; + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'when the "mode" is "wrap", the function wraps out-of-bounds indices', function test( t ) { + var expected; + var indices; + var actual; + + indices = [ -10, 10, -5, 5 ]; + actual = scattered( 4, indices, [ 100, 200, 300, 400 ], 'wrap' ); + expected = [ 0, 400, 200, 300 ]; + + t.strictEqual( isArray( actual ), true, 'returns expected value' ); + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/slice/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/slice/docs/types/index.d.ts index 16a1075f880c..748041306db3 100644 --- a/lib/node_modules/@stdlib/array/base/slice/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/slice/docs/types/index.d.ts @@ -20,7 +20,7 @@ /// -import { Collection, TypedArray, ComplexTypedArray } from '@stdlib/types/array'; +import { Collection, TypedArray, ComplexTypedArray, BooleanTypedArray } from '@stdlib/types/array'; /** * Returns a shallow copy of a portion of an array. @@ -46,7 +46,7 @@ import { Collection, TypedArray, ComplexTypedArray } from '@stdlib/types/array'; * var out = slice( x, 0, 3 ); * // returns [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] */ -declare function slice( x: T, start: number, end: number ): T; +declare function slice( x: T, start: number, end: number ): T; /** * Returns a shallow copy of a portion of an array. diff --git a/lib/node_modules/@stdlib/array/base/slice/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/slice/docs/types/test.ts index 9ddfc3d1ee0e..af3213bed67a 100644 --- a/lib/node_modules/@stdlib/array/base/slice/docs/types/test.ts +++ b/lib/node_modules/@stdlib/array/base/slice/docs/types/test.ts @@ -18,6 +18,7 @@ import Complex128Array = require( '@stdlib/array/complex128' ); import Complex64Array = require( '@stdlib/array/complex64' ); +import BooleanArray = require( '@stdlib/array/bool' ); import slice = require( './index' ); @@ -37,6 +38,7 @@ import slice = require( './index' ); slice( new Uint8ClampedArray( [ 1, 2, 3 ] ), 0, 3 ); // $ExpectType Uint8ClampedArray slice( new Complex128Array( [ 1, 2, 3, 4, 5, 6 ] ), 0, 3 ); // $ExpectType Complex128Array slice( new Complex64Array( [ 1, 2, 3, 4, 5, 6 ] ), 0, 3 ); // $ExpectType Complex64Array + slice( new BooleanArray( [ true, false, true, false ] ), 0, 3 ); // $ExpectType BooleanArray } // The compiler throws an error if the function is provided a first argument which is not a collection... diff --git a/lib/node_modules/@stdlib/array/base/take-indexed/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/take-indexed/docs/types/index.d.ts index 9c642c062a13..c8a47d8ac579 100644 --- a/lib/node_modules/@stdlib/array/base/take-indexed/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/array/base/take-indexed/docs/types/index.d.ts @@ -23,7 +23,7 @@ import { Collection } from '@stdlib/types/array'; /** -* Takes element from an indexed array. +* Takes elements from an indexed array. * * ## Notes * diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/README.md b/lib/node_modules/@stdlib/array/base/take-indexed2/README.md new file mode 100644 index 000000000000..2b1592521f2f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/README.md @@ -0,0 +1,117 @@ + + +# takeIndexed2 + +> Take elements from two indexed arrays in a single pass. + +
+ +## Usage + +```javascript +var takeIndexed2 = require( '@stdlib/array/base/take-indexed2' ); +``` + +#### takeIndexed2( x, y, indices ) + +Takes elements from two indexed arrays in a single pass. + +```javascript +var x = [ 1, 2, 3, 4 ]; +var y = [ 5, 6, 7, 8 ]; + +var out = takeIndexed2( x, y, [ 1, 3 ] ); +// returns [ [ 2, 4 ], [ 6, 8 ] ] +``` + +If `indices` is an empty array, the function returns empty arrays. + +```javascript +var x = [ 1, 2, 3, 4 ]; +var y = [ 5, 6, 7, 8 ]; + +var out = takeIndexed2( x, y, [] ); +// returns [ [], [] ] +``` + +
+ + + +
+ +## Notes + +- The function does **not** perform bounds checking. If an index is less than zero or greater than the maximum index of `x` or `y`, the value of the corresponding element in the respective output array is undefined. +- An _indexed_ array-like object is a data structure in which one retrieves elements via integer indices using bracket `[]` notation (e.g., `Float64Array`, `Int32Array`, `Array`, etc). This is in contrast to an _accessor_ array-like object in which one retrieves elements using `get` and `set` methods (e.g., `Complex64Array` and `Complex128Array`). + +
+ + + +
+ +## Examples + + + +```javascript +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var linspace = require( '@stdlib/array/base/linspace' ); +var takeIndexed2 = require( '@stdlib/array/base/take-indexed2' ); + +// Generate linearly spaced arrays: +var x = linspace( 0, 100, 11 ); +console.log( x ); + +var y = linspace( 100, 200, 11 ); +console.log( y ); + +// Generate an array of random indices: +var N = discreteUniform( 5, 15 ); +var indices = filledBy( N, discreteUniform.factory( 0, x.length-1 ) ); +console.log( indices ); + +// Take a random sample of elements from `x` and `y`: +var out = takeIndexed2( x, y, indices ); +console.log( out ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/benchmark/benchmark.js b/lib/node_modules/@stdlib/array/base/take-indexed2/benchmark/benchmark.js new file mode 100644 index 000000000000..6866e9e3e1e4 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/benchmark/benchmark.js @@ -0,0 +1,52 @@ +/** +* @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 isArrayArray = require( '@stdlib/assert/is-array-array' ); +var zeroTo = require( '@stdlib/array/base/zero-to' ); +var pkg = require( './../package.json' ).name; +var take2 = require( './../lib' ); + + +// MAIN // + +bench( pkg+'::copy:len=100', function benchmark( b ) { + var x; + var i; + var v; + + x = zeroTo( 100 ); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = take2( x, x, x ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isArrayArray( v ) ) { + b.fail( 'should return an array of arrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/benchmark/benchmark.length.js b/lib/node_modules/@stdlib/array/base/take-indexed2/benchmark/benchmark.length.js new file mode 100644 index 000000000000..beb89cd16b0e --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/benchmark/benchmark.length.js @@ -0,0 +1,99 @@ +/** +* @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 pow = require( '@stdlib/math/base/special/pow' ); +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; +var isArrayArray = require( '@stdlib/assert/is-array-array' ); +var pkg = require( './../package.json' ).name; +var take2 = require( './../lib' ); + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var idx = filledBy( len, discreteUniform( 0, 3 ) ); + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var x; + var v; + var i; + + x = [ 1, 2, 3, 4 ]; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = take2( x, x, idx ); + if ( typeof v !== 'object' ) { + b.fail( 'should return an array' ); + } + } + b.toc(); + if ( !isArrayArray( v ) ) { + b.fail( 'should return an array of arrays' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/docs/repl.txt b/lib/node_modules/@stdlib/array/base/take-indexed2/docs/repl.txt new file mode 100644 index 000000000000..540c0f4a4f3e --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/docs/repl.txt @@ -0,0 +1,36 @@ + +{{alias}}( x, y, indices ) + Takes elements from two indexed arrays in a single pass. + + If `indices` is an empty array, the function returns empty arrays. + + The function does *not* perform bounds checking. If an index is less than + zero or greater than the maximum index of `x` or `y`, the value of the + corresponding element in the respective output array is undefined. + + Parameters + ---------- + x: ArrayLikeObject + First input array. + + y: ArrayLikeObject + Second input array. + + indices: ArrayLikeObject + List of element indices. + + Returns + ------- + out: Array + Output arrays. + + Examples + -------- + > var x = [ 1, 2, 3, 4 ]; + > var y = [ 5, 6, 7, 8 ]; + > var out = {{alias}}( x, y, [ 1, 3 ] ) + [ [ 2, 4 ], [ 6, 8 ] ] + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/docs/types/index.d.ts b/lib/node_modules/@stdlib/array/base/take-indexed2/docs/types/index.d.ts new file mode 100644 index 000000000000..b25eeeecac70 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/docs/types/index.d.ts @@ -0,0 +1,50 @@ +/* +* @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 + +/// + +import { Collection } from '@stdlib/types/array'; + +/** +* Takes elements from two indexed arrays in a single pass. +* +* ## Notes +* +* - The function does **not** perform bounds checking. If an index is less than zero or greater than the maximum index of `x` or `y`, the value of the corresponding element in the respective output array is undefined. +* +* @param x - first input array +* @param y - second input array +* @param indices - list of element indices +* @returns output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var indices = [ 3, 1, 2, 0 ]; +* +* var out = take2( x, y, indices ); +* // returns [ [ 4, 2, 3, 1 ], [ 8, 6, 7, 5 ] ] +*/ +declare function take2( x: Collection, y: Collection, indices: Collection ): [ Array, Array ]; + + +// EXPORTS // + +export = take2; diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/docs/types/test.ts b/lib/node_modules/@stdlib/array/base/take-indexed2/docs/types/test.ts new file mode 100644 index 000000000000..7e41a191bc6e --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/docs/types/test.ts @@ -0,0 +1,68 @@ +/* +* @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. +*/ + +import take2 = require( './index' ); + + +// TESTS // + +// The function returns an array of arrays... +{ + take2( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectType [number[], number[]] + take2( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectType [any[], any[]] + take2( [ 1, 2, 3, 4 ], [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectType [number[], number[]] + take2( [ '1', '2', '3', '4' ], [ '1', '2', '3', '4' ], [ 1, 3 ] ); // $ExpectType [string[], string[]] +} + +// The compiler throws an error if the function is provided a first argument which is not an array-like object... +{ + take2( 1, [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectError + take2( true, [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectError + take2( false, [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectError + take2( null, [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectError + take2( void 0, [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectError + take2( {}, [ 1, 2, 3, 4 ], [ 1, 3 ] ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not an array-like object... +{ + take2( [ 1, 2, 3, 4 ], 1, [ 1, 3 ] ); // $ExpectError + take2( [ 1, 2, 3, 4 ], true, [ 1, 3 ] ); // $ExpectError + take2( [ 1, 2, 3, 4 ], false, [ 1, 3 ] ); // $ExpectError + take2( [ 1, 2, 3, 4 ], null, [ 1, 3 ] ); // $ExpectError + take2( [ 1, 2, 3, 4 ], void 0, [ 1, 3 ] ); // $ExpectError + take2( [ 1, 2, 3, 4 ], {}, [ 1, 3 ] ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not an array-like object containing numbers... +{ + take2( [], [], 1 ); // $ExpectError + take2( [], [], true ); // $ExpectError + take2( [], [], false ); // $ExpectError + take2( [], [], null ); // $ExpectError + take2( [], [], void 0 ); // $ExpectError + take2( [], [], {} ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + take2(); // $ExpectError + take2( [] ); // $ExpectError + take2( [], [] ); // $ExpectError + take2( [], [], [], [] ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/examples/index.js b/lib/node_modules/@stdlib/array/base/take-indexed2/examples/index.js new file mode 100644 index 000000000000..0807682421ce --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/examples/index.js @@ -0,0 +1,40 @@ +/** +* @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'; + +var filledBy = require( '@stdlib/array/base/filled-by' ); +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var linspace = require( '@stdlib/array/base/linspace' ); +var take2 = require( './../lib' ); + +// Generate linearly spaced arrays: +var x = linspace( 0, 100, 11 ); +console.log( x ); + +var y = linspace( 100, 200, 11 ); +console.log( y ); + +// Generate an array of random indices: +var N = discreteUniform( 5, 15 ); +var indices = filledBy( N, discreteUniform.factory( 0, x.length-1 ) ); +console.log( indices ); + +// Take a random sample of elements from `x` and `y`: +var out = take2( x, y, indices ); +console.log( out ); diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/lib/index.js b/lib/node_modules/@stdlib/array/base/take-indexed2/lib/index.js new file mode 100644 index 000000000000..4abb5e96c737 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/lib/index.js @@ -0,0 +1,44 @@ +/** +* @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'; + +/** +* Take elements from two indexed arrays in a single pass. +* +* @module @stdlib/array/base/take-indexed2 +* +* @example +* var take2 = require( '@stdlib/array/base/take-indexed2' ); +* +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var indices = [ 3, 1, 2, 0 ]; +* +* var out = take2( x, y, indices ); +* // returns [ [ 4, 2, 3, 1 ], [ 8, 6, 7, 5 ] ] +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/lib/main.js b/lib/node_modules/@stdlib/array/base/take-indexed2/lib/main.js new file mode 100644 index 000000000000..5fb5b2121ec1 --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/lib/main.js @@ -0,0 +1,56 @@ +/** +* @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'; + +// MAIN // + +/** +* Takes elements from two indexed arrays in a single pass. +* +* @param {Collection} x - first input array +* @param {Collection} y - second input array +* @param {NonNegativeIntegerArray} indices - list of indices +* @returns {Array} output arrays +* +* @example +* var x = [ 1, 2, 3, 4 ]; +* var y = [ 5, 6, 7, 8 ]; +* var indices = [ 3, 1, 2, 0 ]; +* +* var out = take2( x, y, indices ); +* // returns [ [ 4, 2, 3, 1 ], [ 8, 6, 7, 5 ] ] +*/ +function take2( x, y, indices ) { + var o1; + var o2; + var i; + + o1 = []; + o2 = []; + for ( i = 0; i < indices.length; i++ ) { + o1.push( x[ indices[ i ] ] ); // use `Array#push` to ensure "fast" elements + o2.push( y[ indices[ i ] ] ); + } + return [ o1, o2 ]; +} + + +// EXPORTS // + +module.exports = take2; diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/package.json b/lib/node_modules/@stdlib/array/base/take-indexed2/package.json new file mode 100644 index 000000000000..1cd89957047f --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/package.json @@ -0,0 +1,62 @@ +{ + "name": "@stdlib/array/base/take-indexed2", + "version": "0.0.0", + "description": "Take elements from two indexed arrays in a single pass.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "utilities", + "utils", + "generic", + "array", + "take", + "extract", + "copy", + "index" + ] +} diff --git a/lib/node_modules/@stdlib/array/base/take-indexed2/test/test.js b/lib/node_modules/@stdlib/array/base/take-indexed2/test/test.js new file mode 100644 index 000000000000..6502bb07f36a --- /dev/null +++ b/lib/node_modules/@stdlib/array/base/take-indexed2/test/test.js @@ -0,0 +1,105 @@ +/** +* @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 tape = require( 'tape' ); +var take2 = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof take2, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function takes elements from two arrays', function test( t ) { + var expected; + var indices; + var actual; + var x; + var y; + + x = [ 1, 2, 3, 4 ]; + y = [ 5, 6, 7, 8 ]; + + indices = [ 1, 3 ]; + actual = take2( x, y, indices ); + expected = [ + [ 2, 4 ], + [ 6, 8 ] + ]; + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 3, 3 ]; + actual = take2( x, y, indices ); + expected = [ + [ 2, 2, 4, 4 ], + [ 6, 6, 8, 8 ] + ]; + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 3, 2, 1, 0 ]; + actual = take2( x, y, indices ); + expected = [ + [ 4, 3, 2, 1 ], + [ 8, 7, 6, 5 ] + ]; + t.deepEqual( actual, expected, 'returns expected value' ); + + indices = [ 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 ]; + actual = take2( x, y, indices ); + expected = [ + [ 2, 2, 2, 2, 2, 2, 2, 2, 2, 2 ], + [ 6, 6, 6, 6, 6, 6, 6, 6, 6, 6 ] + ]; + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function does not perform bounds checking', function test( t ) { + var expected; + var indices; + var actual; + var x; + var y; + + x = [ 1, 2, 3, 4 ]; + y = [ 5, 6, 7, 8 ]; + + indices = [ 4, 5, 1, 2 ]; + actual = take2( x, y, indices ); + expected = [ + [ void 0, void 0, 2, 3 ], + [ void 0, void 0, 6, 7 ] + ]; + t.deepEqual( actual, expected, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function returns empty arrays if provided a third argument which is empty', function test( t ) { + var x = [ 1, 2, 3, 4 ]; + t.deepEqual( take2( x, x, [] ), [ [], [] ], 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/array/base/zeros3d/README.md b/lib/node_modules/@stdlib/array/base/zeros3d/README.md index c82e7c1ac869..b7b30ddee9fd 100644 --- a/lib/node_modules/@stdlib/array/base/zeros3d/README.md +++ b/lib/node_modules/@stdlib/array/base/zeros3d/README.md @@ -95,6 +95,17 @@ out = zeros3d( [ 1, 3, 1 ] ); @@ -103,6 +114,22 @@ out = zeros3d( [ 1, 3, 1 ] ); diff --git a/lib/node_modules/@stdlib/array/fixed-endian-float32/README.md b/lib/node_modules/@stdlib/array/fixed-endian-float32/README.md index e5218ccebff8..65469eb4528d 100644 --- a/lib/node_modules/@stdlib/array/fixed-endian-float32/README.md +++ b/lib/node_modules/@stdlib/array/fixed-endian-float32/README.md @@ -422,6 +422,13 @@ logEach( '%s', out ); @@ -438,6 +445,12 @@ logEach( '%s', out ); [@stdlib/array/float32]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/float32 + + +[@stdlib/array/fixed-endian-float64]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/array/fixed-endian-float64 + + + diff --git a/lib/node_modules/@stdlib/array/float32/README.md b/lib/node_modules/@stdlib/array/float32/README.md index e48de663268f..3f4796534797 100644 --- a/lib/node_modules/@stdlib/array/float32/README.md +++ b/lib/node_modules/@stdlib/array/float32/README.md @@ -233,8 +233,8 @@ var arr = Float32Array.from( [ 1.0, 2.0 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -371,9 +371,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -490,9 +490,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -552,9 +552,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -615,9 +615,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -670,9 +670,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -893,9 +893,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -957,10 +957,10 @@ var v = arr.reduce( fcn, 0.0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1000,10 +1000,10 @@ var v = arr.reduce( fcn, 0.0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1176,9 +1176,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/float64/README.md b/lib/node_modules/@stdlib/array/float64/README.md index 9e2abee7bc66..ee04993e6922 100644 --- a/lib/node_modules/@stdlib/array/float64/README.md +++ b/lib/node_modules/@stdlib/array/float64/README.md @@ -229,8 +229,8 @@ var arr = Float64Array.from( [ 1.0, -1.0 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -885,9 +885,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -949,10 +949,10 @@ var v = arr.reduce( fcn, 0.0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -992,10 +992,10 @@ var v = arr.reduce( fcn, 0.0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1168,9 +1168,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/int16/README.md b/lib/node_modules/@stdlib/array/int16/README.md index 1a577098baee..3a165efea386 100644 --- a/lib/node_modules/@stdlib/array/int16/README.md +++ b/lib/node_modules/@stdlib/array/int16/README.md @@ -229,8 +229,8 @@ var arr = Int16Array.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/int32/README.md b/lib/node_modules/@stdlib/array/int32/README.md index c9215ea7a37e..45def2674ec2 100644 --- a/lib/node_modules/@stdlib/array/int32/README.md +++ b/lib/node_modules/@stdlib/array/int32/README.md @@ -229,8 +229,8 @@ var arr = Int32Array.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/int8/README.md b/lib/node_modules/@stdlib/array/int8/README.md index 545894ac08e9..50288ee35f70 100644 --- a/lib/node_modules/@stdlib/array/int8/README.md +++ b/lib/node_modules/@stdlib/array/int8/README.md @@ -229,8 +229,8 @@ var arr = Int8Array.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/to-fancy/README.md b/lib/node_modules/@stdlib/array/to-fancy/README.md index abb3b16e8c24..e78a9971b8ee 100644 --- a/lib/node_modules/@stdlib/array/to-fancy/README.md +++ b/lib/node_modules/@stdlib/array/to-fancy/README.md @@ -37,7 +37,7 @@ var x = [ 1, 2, 3, 4, 5, 6, 7, 8 ]; // Turn the plain array into a "fancy" array: var y = array2fancy( x ); -// Select the first 3 elements: +// Select the first three elements: var v = y[ ':3' ]; // returns [ 1, 2, 3 ] @@ -45,7 +45,7 @@ var v = y[ ':3' ]; v = y[ '1::2' ]; // returns [ 2, 4, 6, 8 ] -// Select every other element, in reverse order, starting with the least element: +// Select every other element, in reverse order, starting with the last element: v = y[ '::-2' ]; // returns [ 8, 6, 4, 2 ] diff --git a/lib/node_modules/@stdlib/array/uint16/README.md b/lib/node_modules/@stdlib/array/uint16/README.md index f1962df57fd5..159606fe33ff 100644 --- a/lib/node_modules/@stdlib/array/uint16/README.md +++ b/lib/node_modules/@stdlib/array/uint16/README.md @@ -229,8 +229,8 @@ var arr = Uint16Array.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/uint32/README.md b/lib/node_modules/@stdlib/array/uint32/README.md index c081d0e2ff33..da419b7ac2d8 100644 --- a/lib/node_modules/@stdlib/array/uint32/README.md +++ b/lib/node_modules/@stdlib/array/uint32/README.md @@ -229,8 +229,8 @@ var arr = Uint32Array.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index.. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/uint8/README.md b/lib/node_modules/@stdlib/array/uint8/README.md index 53b5170784f6..7adbddf55bce 100644 --- a/lib/node_modules/@stdlib/array/uint8/README.md +++ b/lib/node_modules/@stdlib/array/uint8/README.md @@ -229,8 +229,8 @@ var arr = Uint8Array.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/array/uint8c/README.md b/lib/node_modules/@stdlib/array/uint8c/README.md index aa4caf80a488..de33ece9549b 100644 --- a/lib/node_modules/@stdlib/array/uint8c/README.md +++ b/lib/node_modules/@stdlib/array/uint8c/README.md @@ -229,8 +229,8 @@ var arr = Uint8ClampedArray.from( [ 1, 2 ], mapFcn ); A callback function is provided two arguments: -- `value`: source value -- `index`: source index +- `value`: source value. +- `index`: source index. To set the callback execution context, provide a `thisArg`. @@ -363,9 +363,9 @@ var bool = arr.every( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -482,9 +482,9 @@ var arr2 = arr1.filter( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -544,9 +544,9 @@ var v = arr.find( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -607,9 +607,9 @@ var idx = arr.findIndex( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -662,9 +662,9 @@ console.log( str ); The callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -879,9 +879,9 @@ var arr2 = arr1.map( fcn ); A callback is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. @@ -943,10 +943,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -986,10 +986,10 @@ var v = arr.reduce( fcn, 0 ); A callback is provided four arguments: -- `acc`: accumulated result -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `acc`: accumulated result. +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. @@ -1162,9 +1162,9 @@ var bool = arr.some( predicate ); A `predicate` function is provided three arguments: -- `value`: array element -- `index`: array index -- `arr`: array on which the method is invoked +- `value`: array element. +- `index`: array index. +- `arr`: array on which the method is invoked. To set the callback execution context, provide a `thisArg`. diff --git a/lib/node_modules/@stdlib/assert/docs/types/index.d.ts b/lib/node_modules/@stdlib/assert/docs/types/index.d.ts index cc62ce665707..f33d9927759e 100644 --- a/lib/node_modules/@stdlib/assert/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/assert/docs/types/index.d.ts @@ -2643,7 +2643,7 @@ interface Namespace { * * - The function validates that a value is a string. For all other types, the function returns `false`. * - * - A duration string is a string containing a sequence of time units. A time unit is a non-negative integer followed by a unit identifier. The following unit identifiers are supported: + * - A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported: * * - `d`: days * - `h`: hours diff --git a/lib/node_modules/@stdlib/assert/is-duration-string/README.md b/lib/node_modules/@stdlib/assert/is-duration-string/README.md index 91228b698dbb..ef825221f69a 100644 --- a/lib/node_modules/@stdlib/assert/is-duration-string/README.md +++ b/lib/node_modules/@stdlib/assert/is-duration-string/README.md @@ -52,7 +52,7 @@ bool = isDurationString( '1d2h' ); - The function validates that a `value` is a `string`. For all other types, the function returns `false`. -- A duration string is a string containing a sequence of time units. A time unit is a non-negative integer followed by a unit identifier. The following unit identifiers are supported: +- A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported: - `d`: days - `h`: hours diff --git a/lib/node_modules/@stdlib/assert/is-duration-string/docs/repl.txt b/lib/node_modules/@stdlib/assert/is-duration-string/docs/repl.txt index 56266b319ca3..6ad4b1bedc48 100644 --- a/lib/node_modules/@stdlib/assert/is-duration-string/docs/repl.txt +++ b/lib/node_modules/@stdlib/assert/is-duration-string/docs/repl.txt @@ -6,7 +6,7 @@ function returns `false`. A duration string is a string containing a sequence of time units. A time - unit is a non-negative integer followed by a unit identifier. The following + unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported: - d: days. diff --git a/lib/node_modules/@stdlib/assert/is-duration-string/docs/types/index.d.ts b/lib/node_modules/@stdlib/assert/is-duration-string/docs/types/index.d.ts index 0ac9bd4149b1..fc8b61e61b64 100644 --- a/lib/node_modules/@stdlib/assert/is-duration-string/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/assert/is-duration-string/docs/types/index.d.ts @@ -25,7 +25,7 @@ * * - The function validates that a value is a string. For all other types, the function returns `false`. * -* - A duration string is a string containing a sequence of time units. A time unit is a non-negative integer followed by a unit identifier. The following unit identifiers are supported: +* - A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported: * * - `d`: days * - `h`: hours diff --git a/lib/node_modules/@stdlib/assert/is-duration-string/lib/main.js b/lib/node_modules/@stdlib/assert/is-duration-string/lib/main.js index b8627af0ce11..2d03f81f908a 100644 --- a/lib/node_modules/@stdlib/assert/is-duration-string/lib/main.js +++ b/lib/node_modules/@stdlib/assert/is-duration-string/lib/main.js @@ -37,7 +37,7 @@ var RE_DURATION_STRING = /^(?:\d+d)?(?:\d+h)?(?:\d+m)?(?:\d+s)?(?:\d+ms)?$/i; * * - The function validates that a value is a string. For all other types, the function returns `false`. * -* - A duration string is a string containing a sequence of time units. A time unit is a non-negative integer followed by a unit identifier. The following unit identifiers are supported: +* - A duration string is a string containing a sequence of time units. A time unit is a nonnegative integer followed by a unit identifier. The following unit identifiers are supported: * * - `d`: days * - `h`: hours diff --git a/lib/node_modules/@stdlib/assert/is-pascalcase/README.md b/lib/node_modules/@stdlib/assert/is-pascalcase/README.md index 1cdab12cd475..2c816747b526 100644 --- a/lib/node_modules/@stdlib/assert/is-pascalcase/README.md +++ b/lib/node_modules/@stdlib/assert/is-pascalcase/README.md @@ -166,6 +166,12 @@ true @@ -180,6 +186,8 @@ true +[@stdlib/assert/is-string]: https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/assert/is-string + diff --git a/lib/node_modules/@stdlib/assert/is-property-key/test/test.js b/lib/node_modules/@stdlib/assert/is-property-key/test/test.js index 603e15a5879d..172e80697f74 100644 --- a/lib/node_modules/@stdlib/assert/is-property-key/test/test.js +++ b/lib/node_modules/@stdlib/assert/is-property-key/test/test.js @@ -54,14 +54,14 @@ tape( 'the function returns `true` if provided a symbol primitive', opts, functi t.end(); }); -tape( 'the function returns `true` if provided a non-negative integer primitive', function test( t ) { +tape( 'the function returns `true` if provided a nonnegative integer primitive', function test( t ) { t.strictEqual( isPropertyKey( 0 ), true, 'returns true' ); t.strictEqual( isPropertyKey( 1 ), true, 'returns true' ); t.strictEqual( isPropertyKey( 139 ), true, 'returns true' ); t.end(); }); -tape( 'the function returns `false` if not provided a string, symbol, or non-negative integer primitive', function test( t ) { +tape( 'the function returns `false` if not provided a string, symbol, or nonnegative integer primitive', function test( t ) { var values; var i; @@ -77,7 +77,7 @@ tape( 'the function returns `false` if not provided a string, symbol, or non-neg [], function noop() {}, new String( 'beep' ), // eslint-disable-line no-new-wrappers - new Number( 1 ) // eslint-disable-line no-new-wrappers + new Number( 1 ) ]; for ( i = 0; i < values.length; i++ ) { diff --git a/lib/node_modules/@stdlib/blas/base/cscal/README.md b/lib/node_modules/@stdlib/blas/base/cscal/README.md index 5ff72d193ef5..262c37244d5e 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/README.md +++ b/lib/node_modules/@stdlib/blas/base/cscal/README.md @@ -37,28 +37,18 @@ Scales values from `cx` by `ca`. ```javascript var Complex64Array = require( '@stdlib/array/complex64' ); var Complex64 = require( '@stdlib/complex/float32/ctor' ); -var realf = require( '@stdlib/complex/float32/real' ); -var imagf = require( '@stdlib/complex/float32/imag' ); var cx = new Complex64Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] ); var ca = new Complex64( 2.0, 0.0 ); cscal( 3, ca, cx, 1 ); - -var z = cx.get( 0 ); -// returns - -var re = realf( z ); -// returns 2.0 - -var im = imagf( z ); -// returns 2.0 +// cx => [ 2.0, 2.0, 2.0, 1.0, 1.0, 1.0 ] ``` The function has the following parameters: - **N**: number of indexed elements. -- **ca**: scalar [`Complex64`][@stdlib/complex/float32/ctor] constant. +- **ca**: scalar [`Complex64`][@stdlib/complex/float32/ctor] constant. - **cx**: input [`Complex64Array`][@stdlib/array/complex64]. - **strideX**: index increment for `cx`. @@ -67,22 +57,12 @@ The `N` and stride parameters determine how values from `cx` are scaled by `ca`. ```javascript var Complex64Array = require( '@stdlib/array/complex64' ); var Complex64 = require( '@stdlib/complex/float32/ctor' ); -var realf = require( '@stdlib/complex/float32/real' ); -var imagf = require( '@stdlib/complex/float32/imag' ); var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); var ca = new Complex64( 2.0, 0.0 ); cscal( 2, ca, cx, 2 ); - -var z = cx.get( 2 ); -// returns - -var re = realf( z ); -// returns 10.0 - -var im = imagf( z ); -// returns 12.0 +// cx => [ 1.0, 2.0, 10.0, 12.0, 5.0, 6.0, 14.0, 16.0 ] ``` Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. @@ -92,8 +72,6 @@ Note that indexing is relative to the first index. To introduce an offset, use [ ```javascript var Complex64Array = require( '@stdlib/array/complex64' ); var Complex64 = require( '@stdlib/complex/float32/ctor' ); -var realf = require( '@stdlib/complex/float32/real' ); -var imagf = require( '@stdlib/complex/float32/imag' ); // Initial array: var cx0 = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); @@ -106,15 +84,7 @@ var cx1 = new Complex64Array( cx0.buffer, cx0.BYTES_PER_ELEMENT*1 ); // start at // Scales every other value from `cx1` by `ca`... cscal( 3, ca, cx1, 1 ); - -var z = cx0.get( 1 ); -// returns - -var re = realf( z ); -// returns -2.0 - -var im = imagf( z ); -// returns 14.0 +// cx = [ -2.0, 14.0, -2.0, 22.0, -2.0, 30.0, 5.0, 6.0 ] ``` #### cscal.ndarray( N, ca, cx, strideX, offsetX ) @@ -124,22 +94,12 @@ Scales values from `cx` by `ca` using alternative indexing semantics. ```javascript var Complex64Array = require( '@stdlib/array/complex64' ); var Complex64 = require( '@stdlib/complex/float32/ctor' ); -var realf = require( '@stdlib/complex/float32/real' ); -var imagf = require( '@stdlib/complex/float32/imag' ); var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); var ca = new Complex64( 2.0, 2.0 ); cscal.ndarray( 3, ca, cx, 1, 0 ); - -var z = cx.get( 0 ); -// returns - -var re = realf( z ); -// returns -2.0 - -var im = imagf( z ); -// returns 6.0 +// cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 26.0 ] ``` The function has the following additional parameters: @@ -151,22 +111,12 @@ While [`typed array`][mdn-typed-array] views mandate a view offset based on the ```javascript var Complex64Array = require( '@stdlib/array/complex64' ); var Complex64 = require( '@stdlib/complex/float32/ctor' ); -var realf = require( '@stdlib/complex/float32/real' ); -var imagf = require( '@stdlib/complex/float32/imag' ); var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); var ca = new Complex64( 2.0, 2.0 ); cscal.ndarray( 2, ca, cx, 2, 1 ); - -var z = cx.get( 3 ); -// returns - -var re = realf( z ); -// returns -2.0 - -var im = imagf( z ); -// returns 30.0 +// cx => [ 1.0, 2.0, -2.0, 30.0, 5.0, 6.0, -6.0, 58.0 ] ``` diff --git a/lib/node_modules/@stdlib/blas/base/cscal/docs/repl.txt b/lib/node_modules/@stdlib/blas/base/cscal/docs/repl.txt index 894daacaf6c1..3cc4daff11dc 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/docs/repl.txt +++ b/lib/node_modules/@stdlib/blas/base/cscal/docs/repl.txt @@ -37,32 +37,20 @@ > var cx = new {{alias:@stdlib/array/complex64}}( [ 1.0, 2.0, 3.0, 4.0 ] ); > var ca = new {{alias:@stdlib/complex/float32/ctor}}( 1.0, 2.0 ); > {{alias}}( 2, ca, cx, 1 ); - > var z = cx.get( 0 ); - > var re = {{alias:@stdlib/complex/float32/real}}( z ) - -3.0 - > var im = {{alias:@stdlib/complex/float32/imag}}( z ) - 4.0 + [ 2.0, 2.0, 2.0, 1.0 ] // Advanced indexing: > cx = new {{alias:@stdlib/array/complex64}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); > ca = new {{alias:@stdlib/complex/float32/ctor}}( 1.0, 1.0 ); > {{alias}}( 2, ca, cx, 2 ); - > z = cx.get( 0 ); - > re = {{alias:@stdlib/complex/float32/real}}( z ) - -1.0 - > im = {{alias:@stdlib/complex/float32/imag}}( z ) - 3.0 + [ 1.0, 2.0, 10.0, 12.0, 5.0, 6.0 ] // Using typed array views: > var cx0 = new {{alias:@stdlib/array/complex64}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); > var cx1 = new {{alias:@stdlib/array/complex64}}( cx0.buffer, cx0.BYTES_PER_ELEMENT*1 ); > var ca = new {{alias:@stdlib/complex/float32/ctor}}( 2.0, 2.0 ); > {{alias}}( 2, ca, cx1, 1 ); - > z = cx0.get( 1 ); - > re = {{alias:@stdlib/complex/float32/real}}( z ) - -2.0 - > im = {{alias:@stdlib/complex/float32/imag}}( z ) - 14.0 + [ -2.0, 14.0, -2.0, 22.0, -2.0, 30.0 ] {{alias}}.ndarray( N, ca, cx, strideX, offsetX ) @@ -102,21 +90,13 @@ > var cx = new {{alias:@stdlib/array/complex64}}( [ 1.0, 2.0, 3.0, 4.0 ] ); > var ca = new {{alias:@stdlib/complex/float32/ctor}}( 2.0, 2.0 ); > {{alias}}.ndarray( 2, ca, cx, 1, 0 ); - > var z = cx.get( 0 ); - > var re = {{alias:@stdlib/complex/float32/real}}( z ) - -2.0 - > var im = {{alias:@stdlib/complex/float32/imag}}( z ) - 6.0 + [ 0.0, 4.0, -2.0, 10.0 ] // Advanced indexing: > cx = new {{alias:@stdlib/array/complex64}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); > ca = new {{alias:@stdlib/complex/float32/ctor}}( 1.0, 2.0 ); > {{alias}}.ndarray( 2, ca, cx, 1, 2 ); - > z = cx.get( 2 ); - > re = {{alias:@stdlib/complex/float32/real}}( z ) - -7.0 - > im = {{alias:@stdlib/complex/float32/imag}}( z ) - 16.0 + [ 1.0, 2.0, -5.0, 10.0, 5.0, 6.0, -9.0, 22.0 ] See Also -------- diff --git a/lib/node_modules/@stdlib/blas/base/cscal/docs/types/index.d.ts b/lib/node_modules/@stdlib/blas/base/cscal/docs/types/index.d.ts index 07b49959ce4a..03a855242e7b 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/blas/base/cscal/docs/types/index.d.ts @@ -39,22 +39,12 @@ interface Routine { * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); - * var realf = require( '@stdlib/complex/float32/real' ); - * var imagf = require( '@stdlib/complex/float32/imag' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( 3, ca, cx, 1 ); - * - * var z = cx.get( 0 ); - * // returns - * - * var re = realf( z ); - * // returns -2.0 - * - * var im = imagf( z ); - * // returns 6.0 + * // cx = [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ ( N: number, ca: Complex64, cx: Complex64Array, strideX: number ): Complex64Array; @@ -71,22 +61,12 @@ interface Routine { * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); - * var realf = require( '@stdlib/complex/float32/real' ); - * var imagf = require( '@stdlib/complex/float32/imag' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal.ndarray( 3, ca, cx, 1, 0 ); - * - * var z = cx.get( 0 ); - * // returns - * - * var re = realf( z ); - * // returns -2.0 - * - * var im = imagf( z ); - * // returns 6.0 + * // cx = [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ ndarray( N: number, ca: Complex64, cx: Complex64Array, strideX: number, offsetX: number ): Complex64Array; } @@ -103,42 +83,22 @@ interface Routine { * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); -* var realf = require( '@stdlib/complex/float32/real' ); -* var imagf = require( '@stdlib/complex/float32/imag' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( 3, ca, cx, 1 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx = [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] * * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); -* var realf = require( '@stdlib/complex/float32/real' ); -* var imagf = require( '@stdlib/complex/float32/imag' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal.ndarray( 2, ca, cx, 1, 0 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx = [ -2.0, 6.0, -2.0, 14.0, 5.0, 6.0 ] */ declare var cscal: Routine; diff --git a/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.js b/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.js index 3972bf276145..4ea634a38986 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.js +++ b/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.js @@ -45,15 +45,7 @@ var ndarray = require( './ndarray.js' ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( 3, ca, cx, 1 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ function cscal( N, ca, cx, strideX ) { var ox = stride2offset( N, strideX ); diff --git a/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.native.js b/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.native.js index d78d3b077d9d..f635cd9b98fc 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.native.js +++ b/lib/node_modules/@stdlib/blas/base/cscal/lib/cscal.native.js @@ -38,22 +38,12 @@ var addon = require( './../src/addon.node' ); * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); -* var realf = require( '@stdlib/complex/float32/real' ); -* var imagf = require( '@stdlib/complex/float32/imag' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( cx.length, ca, cx, 1 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ function cscal( N, ca, cx, strideX ) { var viewCX = reinterpret( cx, 0 ); diff --git a/lib/node_modules/@stdlib/blas/base/cscal/lib/index.js b/lib/node_modules/@stdlib/blas/base/cscal/lib/index.js index 89ba26de16fa..693de614b983 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/lib/index.js +++ b/lib/node_modules/@stdlib/blas/base/cscal/lib/index.js @@ -26,44 +26,24 @@ * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); -* var realf = require( '@stdlib/complex/float32/real' ); -* var imagf = require( '@stdlib/complex/float32/imag' ); * var cscal = require( '@stdlib/blas/base/cscal' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( 3, ca, cx, 1 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] * * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); -* var realf = require( '@stdlib/complex/float32/real' ); -* var imagf = require( '@stdlib/complex/float32/imag' ); * var cscal = require( '@stdlib/blas/base/cscal' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal.ndarray( 3, ca cx, 1, 0 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ // MODULES // diff --git a/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.js b/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.js index 6b56245e080c..67d642f1b483 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.js +++ b/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.js @@ -38,22 +38,12 @@ var cmulf = require( '@stdlib/complex/float32/base/mul' ); * @example * var Complex64Array = require( '@stdlib/array/complex64' ); * var Complex64 = require( '@stdlib/complex/float32/ctor' ); -* var realf = require( '@stdlib/complex/float32/real' ); -* var imagf = require( '@stdlib/complex/float32/imag' ); * * var cx = new Complex64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( 3, ca, cx, 1, 0 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ function cscal( N, ca, cx, strideX, offsetX ) { var ix; diff --git a/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.native.js b/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.native.js index ad22c3f43488..d4cd7b0af3d2 100644 --- a/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.native.js +++ b/lib/node_modules/@stdlib/blas/base/cscal/lib/ndarray.native.js @@ -46,15 +46,7 @@ var addon = require( './../src/addon.node' ); * var ca = new Complex64( 2.0, 2.0 ); * * cscal( cx.length, ca, cx, 1, 0 ); -* -* var z = cx.get( 0 ); -* // returns -* -* var re = realf( z ); -* // returns -2.0 -* -* var im = imagf( z ); -* // returns 6.0 +* // cx => [ -2.0, 6.0, -2.0, 14.0, -2.0, 22.0 ] */ function cscal( N, ca, cx, strideX, offsetX ) { var viewCX = reinterpret( cx, 0 ); diff --git a/lib/node_modules/@stdlib/blas/base/drotm-wasm/README.md b/lib/node_modules/@stdlib/blas/base/drotm-wasm/README.md index bda4dcbfb039..e2991dc4a44b 100644 --- a/lib/node_modules/@stdlib/blas/base/drotm-wasm/README.md +++ b/lib/node_modules/@stdlib/blas/base/drotm-wasm/README.md @@ -53,7 +53,7 @@ The function has the following parameters: - **strideX**: index increment for `x`. - **y**: input [`Float64Array`][@stdlib/array/float64]. - **strideY**: index increment for `y`. -- **param**: parameters for the modified Givens transformation +- **param**: parameters for the modified Givens transformation. The `N` and stride parameters determine how values in the strided arrays are accessed at runtime. For example, to apply a modified Givens plane rotation to every other element, diff --git a/lib/node_modules/@stdlib/blas/base/drotm/README.md b/lib/node_modules/@stdlib/blas/base/drotm/README.md index 1c3cbd622814..40e183f70ff2 100644 --- a/lib/node_modules/@stdlib/blas/base/drotm/README.md +++ b/lib/node_modules/@stdlib/blas/base/drotm/README.md @@ -53,7 +53,7 @@ The function has the following parameters: - **strideX**: index increment for `x`. - **y**: second input [`Float64Array`][mdn-float64array]. - **strideY**: index increment for `y`. -- **param**: parameters for the modified Givens transformation +- **param**: parameters for the modified Givens transformation. The `N` and stride parameters determine how values in the strided arrays are accessed at runtime. For example, to apply a modified Givens plane rotation to every other element, diff --git a/lib/node_modules/@stdlib/blas/base/saxpy/README.md b/lib/node_modules/@stdlib/blas/base/saxpy/README.md index efac1e63552e..d8dc513995ac 100644 --- a/lib/node_modules/@stdlib/blas/base/saxpy/README.md +++ b/lib/node_modules/@stdlib/blas/base/saxpy/README.md @@ -307,8 +307,8 @@ int main( void ) { ## See Also -- [`@stdlib/blas/base/daxpy`][@stdlib/blas/base/daxpy]: multiply a vector x by a constant and add the result to y. -- [`@stdlib/blas/base/gaxpy`][@stdlib/blas/base/gaxpy]: multiply x by a constant and add the result to y. +- [`@stdlib/blas/base/daxpy`][@stdlib/blas/base/daxpy]: multiply a vector `x` by a constant and add the result to `y`. +- [`@stdlib/blas/base/gaxpy`][@stdlib/blas/base/gaxpy]: multiply a vector `x` by a constant and add the result to `y`. diff --git a/lib/node_modules/@stdlib/blas/base/sgemm/README.md b/lib/node_modules/@stdlib/blas/base/sgemm/README.md index e3356fcbab40..2f77a3779901 100644 --- a/lib/node_modules/@stdlib/blas/base/sgemm/README.md +++ b/lib/node_modules/@stdlib/blas/base/sgemm/README.md @@ -58,7 +58,7 @@ The function has the following parameters: - **lda**: stride of the first dimension of `A` (leading dimension of `A`). - **B**: second input matrix stored in linear memory as a [`Float32Array`][mdn-float32array]. - **ldb**: stride of the first dimension of `B` (leading dimension of `B`). -- **β**: scalar constant +- **β**: scalar constant. - **C**: third input matrix stored in linear memory as a [`Float32Array`][mdn-float32array]. - **ldc**: stride of the first dimension of `C` (leading dimension of `C`). diff --git a/lib/node_modules/@stdlib/blas/base/srotm/README.md b/lib/node_modules/@stdlib/blas/base/srotm/README.md index d5d0fbdf379d..5e1861198e23 100644 --- a/lib/node_modules/@stdlib/blas/base/srotm/README.md +++ b/lib/node_modules/@stdlib/blas/base/srotm/README.md @@ -53,7 +53,7 @@ The function has the following parameters: - **strideX**: index increment for `x`. - **y**: second input [`Float32Array`][mdn-float32array]. - **strideY**: index increment for `y`. -- **param**: parameters for the modified Givens transformation +- **param**: parameters for the modified Givens transformation. The `N` and stride parameters determine how values in the strided arrays are accessed at runtime. For example, to apply a modified Givens plane rotation to every other element, diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/README.md b/lib/node_modules/@stdlib/blas/base/zdscal/README.md new file mode 100644 index 000000000000..4bcd8970c392 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/README.md @@ -0,0 +1,233 @@ + + +# zdscal + +> Scale a double-precision complex floating-point vector by a double-precision floating-point constant. + +
+ +## Usage + +```javascript +var zdscal = require( '@stdlib/blas/base/zdscal' ); +``` + +#### zdscal( N, da, zx, strideZX ) + +Scales a double-precision complex floating-point vector by a double-precision floating-point constant. + +```javascript +var Complex128Array = require( '@stdlib/array/complex128' ); +var real = require( '@stdlib/complex/float64/real' ); +var imag = require( '@stdlib/complex/float64/imag' ); + +var zx = new Complex128Array( [ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ] ); + +zdscal( 3, 2.0, zx, 1 ); + +var z = zx.get( 0 ); +// returns + +var re = real( z ); +// returns 2.0 + +var im = imag( z ); +// returns 2.0 +``` + +The function has the following parameters: + +- **N**: number of indexed elements. +- **da**: scalar constant. +- **zx**: input [`Complex128Array`][@stdlib/array/complex128]. +- **strideZX**: stride length for `zx`. + +The `N` and stride parameters determine which elements in `zx` are scaled by `da`. For example, to scale every other element in `zx` by `da`, + +```javascript +var Complex128Array = require( '@stdlib/array/complex128' ); +var real = require( '@stdlib/complex/float64/real' ); +var imag = require( '@stdlib/complex/float64/imag' ); + +var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + +zdscal( 2, 2.0, zx, 2 ); + +var z = zx.get( 2 ); +// returns + +var re = real( z ); +// returns 10.0 + +var im = imag( z ); +// returns 12.0 +``` + +Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views. + + + +```javascript +var Complex128Array = require( '@stdlib/array/complex128' ); +var real = require( '@stdlib/complex/float64/real' ); +var imag = require( '@stdlib/complex/float64/imag' ); + +// Initial array: +var zx0 = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + +// Create an offset view: +var zx1 = new Complex128Array( zx0.buffer, zx0.BYTES_PER_ELEMENT*1 ); // start at 2nd element + +// Scale every element in `zx1`: +zdscal( 3, 2.0, zx1, 1 ); + +var z = zx0.get( 0 ); +// returns + +var re = real( z ); +// returns 1.0 + +var im = imag( z ); +// returns 2.0 + +z = zx0.get( 1 ); +// returns + +re = real( z ); +// returns 6.0 + +im = imag( z ); +// returns 8.0 +``` + +#### zdscal.ndarray( N, da, zx, strideZX, offsetZX ) + +Scales a double-precision complex floating-point vector by a double-precision floating-point constant using alternative indexing semantics. + +```javascript +var Complex128Array = require( '@stdlib/array/complex128' ); +var real = require( '@stdlib/complex/float64/real' ); +var imag = require( '@stdlib/complex/float64/imag' ); + +var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + +zdscal.ndarray( 3, 2.0, zx, 1, 0 ); + +var z = zx.get( 0 ); +// returns + +var re = real( z ); +// returns 2.0 + +var im = imag( z ); +// returns 4.0 +``` + +The function has the following additional parameters: + +- **offsetZX**: starting index for `zx`. + +While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to scale every other element in the input strided array starting from the second element, + +```javascript +var Complex128Array = require( '@stdlib/array/complex128' ); +var real = require( '@stdlib/complex/float64/real' ); +var imag = require( '@stdlib/complex/float64/imag' ); + +var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + +zdscal.ndarray( 2, 2.0, zx, 2, 1 ); + +var z = zx.get( 3 ); +// returns + +var re = real( z ); +// returns 14.0 + +var im = imag( z ); +// returns 16.0 +``` + +
+ + + +
+ +## Notes + +- If `N <= 0`, both functions return `zx` unchanged. +- `zdscal()` corresponds to the [BLAS][blas] level 1 function [`zdscal`][zdscal]. + +
+ + + +
+ +## Examples + + + +```javascript +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var filledarrayBy = require( '@stdlib/array/filled-by' ); +var Complex128 = require( '@stdlib/complex/float64/ctor' ); +var zdscal = require( '@stdlib/blas/base/zdscal' ); + +function rand() { + return new Complex128( discreteUniform( 0, 10 ), discreteUniform( -5, 5 ) ); +} + +var zx = filledarrayBy( 10, 'complex128', rand ); +console.log( zx.toString() ); + +zdscal( zx.length, 2.0, zx, 1 ); +console.log( zx.toString() ); +``` + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/benchmark/benchmark.js b/lib/node_modules/@stdlib/blas/base/zdscal/benchmark/benchmark.js new file mode 100644 index 000000000000..44194d6be6b4 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/benchmark/benchmark.js @@ -0,0 +1,107 @@ +/** +* @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 uniform = require( '@stdlib/random/array/uniform' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var Complex128Array = require( '@stdlib/array/complex128' ); +var pkg = require( './../package.json' ).name; +var zdscal = require( './../lib/zdscal.js' ); + + +// VARIABLES // + +var options = { + 'dtype': 'float64' +}; + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var zxbuf; + var zx; + + zxbuf = uniform( len*2, -100.0, 100.0, options ); + zx = new Complex128Array( zxbuf.buffer ); + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + zdscal( zx.length, 2.0, zx, 1 ); + if ( isnan( zxbuf[ i%(len*2) ] ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( zxbuf[ i%(len*2) ] ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/benchmark/benchmark.ndarray.js b/lib/node_modules/@stdlib/blas/base/zdscal/benchmark/benchmark.ndarray.js new file mode 100644 index 000000000000..ebefeb815a35 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/benchmark/benchmark.ndarray.js @@ -0,0 +1,107 @@ +/** +* @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 uniform = require( '@stdlib/random/array/uniform' ); +var isnan = require( '@stdlib/math/base/assert/is-nan' ); +var pow = require( '@stdlib/math/base/special/pow' ); +var Complex128Array = require( '@stdlib/array/complex128' ); +var pkg = require( './../package.json' ).name; +var zdscal = require( './../lib/ndarray.js' ); + + +// VARIABLES // + +var options = { + 'dtype': 'float64' +}; + + +// FUNCTIONS // + +/** +* Creates a benchmark function. +* +* @private +* @param {PositiveInteger} len - array length +* @returns {Function} benchmark function +*/ +function createBenchmark( len ) { + var zxbuf; + var zx; + + zxbuf = uniform( len*2, -100.0, 100.0, options ); + zx = new Complex128Array( zxbuf.buffer ); + + return benchmark; + + /** + * Benchmark function. + * + * @private + * @param {Benchmark} b - benchmark instance + */ + function benchmark( b ) { + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + zdscal( zx.length, 2.0, zx, 1, 0 ); + if ( isnan( zxbuf[ i%(len*2) ] ) ) { + b.fail( 'should not return NaN' ); + } + } + b.toc(); + if ( isnan( zxbuf[ i%(len*2) ] ) ) { + b.fail( 'should not return NaN' ); + } + b.pass( 'benchmark finished' ); + b.end(); + } +} + + +// MAIN // + +/** +* Main execution sequence. +* +* @private +*/ +function main() { + var len; + var min; + var max; + var f; + var i; + + min = 1; // 10^min + max = 6; // 10^max + + for ( i = min; i <= max; i++ ) { + len = pow( 10, i ); + f = createBenchmark( len ); + bench( pkg+':ndarray:len='+len, f ); + } +} + +main(); diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/docs/repl.txt b/lib/node_modules/@stdlib/blas/base/zdscal/docs/repl.txt new file mode 100644 index 000000000000..daf02cf15b11 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/docs/repl.txt @@ -0,0 +1,116 @@ + +{{alias}}( N, da, zx, strideZX ) + Scales a double-precision complex floating-point vector by a double- + precision floating-point constant. + + The `N` and stride parameters determine which elements in `zx` are scaled by + `da`. + + Indexing is relative to the first index. To introduce an offset, use typed + array views. + + If `N` is less than or equal to `0`, the function returns `zx` unchanged. + + + Parameters + ---------- + N: integer + Number of indexed elements. + + da: double + Scalar constant. + + zx: Complex128Array + Input array. + + strideZX: integer + Stride length for `zx`. + + Returns + ------- + zx: Complex128Array + Input array. + + Examples + -------- + // Standard usage: + > var zx = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0 ] ); + > {{alias}}( 2, 2.0, zx, 1 ); + > var z = zx.get( 0 ); + > var re = {{alias:@stdlib/complex/float64/real}}( z ) + 2.0 + > var im = {{alias:@stdlib/complex/float64/imag}}( z ) + 4.0 + + // N and stride parameters: + > zx = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + > {{alias}}( 2, 2.0, zx, 2 ); + > z = zx.get( 2 ); + > re = {{alias:@stdlib/complex/float64/real}}( z ) + 10.0 + > im = {{alias:@stdlib/complex/float64/imag}}( z ) + 12.0 + + // Using typed array views: + > var zx0 = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + > var zx1 = new {{alias:@stdlib/array/complex128}}( zx0.buffer, zx0.BYTES_PER_ELEMENT*1 ); + > {{alias}}( 2, 2.0, zx1, 1 ); + > z = zx0.get( 1 ); + > re = {{alias:@stdlib/complex/float64/real}}( z ) + 6.0 + > im = {{alias:@stdlib/complex/float64/imag}}( z ) + 8.0 + + +{{alias}}.ndarray( N, da, zx, strideZX, offsetZX ) + Scales a double-precision complex floating-point vector by a double- + precision floating-point constant using alternative indexing semantics. + + While typed array views mandate a view offset based on the underlying + buffer, the offset parameter supports indexing semantics based on a starting + index. + + Parameters + ---------- + N: integer + Number of indexed elements. + + da: number + Scalar constant. + + zx: Complex128Array + Input array. + + strideZX: integer + Stride length for `zx`. + + offsetZX: integer + Starting index for `zx`. + + Returns + ------- + zx: Complex128Array + Input array. + + Examples + -------- + // Standard usage: + > var zx = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0 ] ); + > {{alias}}.ndarray( 2, 2.0, zx, 1, 0 ); + > var z = zx.get( 0 ); + > var re = {{alias:@stdlib/complex/float64/real}}( z ) + 2.0 + > var im = {{alias:@stdlib/complex/float64/imag}}( z ) + 4.0 + + // Advanced indexing: + > zx = new {{alias:@stdlib/array/complex128}}( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + > {{alias}}.ndarray( 2, 2.0, zx, 1, 2 ); + > z = zx.get( 2 ); + > re = {{alias:@stdlib/complex/float64/real}}( z ) + 10.0 + > im = {{alias:@stdlib/complex/float64/imag}}( z ) + 12.0 + + See Also + -------- diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/docs/types/index.d.ts b/lib/node_modules/@stdlib/blas/base/zdscal/docs/types/index.d.ts new file mode 100644 index 000000000000..e669d140c00f --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/docs/types/index.d.ts @@ -0,0 +1,139 @@ +/* +* @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 + +/// + +import { Complex128Array } from '@stdlib/types/array'; + +/** +* Interface describing `zdscal`. +*/ +interface Routine { + /** + * Scales a double-precision complex floating-point vector by a double-precision floating-point constant. + * + * @param N - number of indexed elements + * @param za - scalar constant + * @param zx - input array + * @param strideZX - `zx` stride length + * @returns input array + * + * @example + * var Complex128Array = require( '@stdlib/array/complex128' ); + * var real = require( '@stdlib/complex/float64/real' ); + * var imag = require( '@stdlib/complex/float64/imag' ); + * + * var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + * + * zdscal( 3, 2.0, zx, 1 ); + * + * var z = zx.get( 0 ); + * // returns + * + * var re = real( z ); + * // returns 2.0 + * + * var im = imag( z ); + * // returns 4.0 + */ + ( N: number, da: number, zx: Complex128Array, strideZX: number ): Complex128Array; + + /** + * Scales a double-precision complex floating-point vector by a double-precision floating-point constant. + * + * @param N - number of indexed elements + * @param da - scalar constant + * @param zx - input array + * @param strideZX - `zx` stride length + * @param offsetZX - starting index for `zx` + * @returns input array + * + * @example + * var Complex128Array = require( '@stdlib/array/complex128' ); + * var real = require( '@stdlib/complex/float64/real' ); + * var imag = require( '@stdlib/complex/float64/imag' ); + * + * var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); + * + * zdscal.ndarray( 3, 2.0, zx, 1, 0 ); + * + * var z = zx.get( 0 ); + * // returns + * + * var re = real( z ); + * // returns 2.0 + * + * var im = imag( z ); + * // returns 4.0 + */ + ndarray( N: number, da: number, zx: Complex128Array, strideZX: number, offsetZX: number ): Complex128Array; +} + +/** +* Scales a double-precision complex floating-point vector by a double-precision floating-point constant. +* +* @param N - number of indexed elements +* @param da - scalar constant +* @param zx - input array +* @param strideZX - `zx` stride length +* @returns input array +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var real = require( '@stdlib/complex/float64/real' ); +* var imag = require( '@stdlib/complex/float64/imag' ); +* +* var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* zdscal( 3, 2.0, zx, 1 ); +* +* var z = zx.get( 1 ); +* // returns +* +* var re = real( z ); +* // returns 6.0 +* +* var im = imag( z ); +* // returns 8.0 +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var real = require( '@stdlib/complex/float64/real' ); +* var imag = require( '@stdlib/complex/float64/imag' ); +* +* var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* zdscal.ndarray( 2, 2.0, zx, 1, 1 ); +* +* var z = zx.get( 1 ); +* // returns +* +* var re = real( z ); +* // returns 10.0 +* +* var im = imag( z ); +* // returns 12.0 +*/ +declare var zdscal: Routine; + + +// EXPORTS // + +export = zdscal; diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/docs/types/test.ts b/lib/node_modules/@stdlib/blas/base/zdscal/docs/types/test.ts new file mode 100644 index 000000000000..d857869e57da --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/docs/types/test.ts @@ -0,0 +1,191 @@ +/* +* @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. +*/ + +import Complex128Array = require( '@stdlib/array/complex128' ); +import Complex128 = require( '@stdlib/complex/float64/ctor' ); +import zdscal = require( './index' ); + + +// TESTS // + +// The function returns a Complex128Array... +{ + const zx = new Complex128Array( 10 ); + + zdscal( zx.length, 2.0, zx, 1 ); // $ExpectType Complex128Array +} + +// The compiler throws an error if the function is provided a first argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal( '10', 2.0, zx, 1 ); // $EzxpectError + zdscal( true, 2.0, zx, 1 ); // $ExpectError + zdscal( false, 2.0, zx, 1 ); // $ExpectError + zdscal( null, 2.0, zx, 1 ); // $ExpectError + zdscal( undefined, 2.0, zx, 1 ); // $ExpectError + zdscal( [], 2.0, zx, 1 ); // $ExpectError + zdscal( {}, 2.0, zx, 1 ); // $ExpectError + zdscal( ( zx: number ): number => zx, 2.0, zx, 1 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a second argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal( zx.length, new Complex128( 1.0, 2.0 ), zx, 1 ); // $ExpectError + zdscal( zx.length, '10', zx, 1 ); // $ExpectError + zdscal( zx.length, true, zx, 1 ); // $ExpectError + zdscal( zx.length, false, zx, 1 ); // $ExpectError + zdscal( zx.length, null, zx, 1 ); // $ExpectError + zdscal( zx.length, undefined, zx, 1 ); // $ExpectError + zdscal( zx.length, [ '1' ], zx, 1 ); // $ExpectError + zdscal( zx.length, {}, zx, 1 ); // $ExpectError + zdscal( zx.length, ( zx: number ): number => zx, zx, 1 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a third argument which is not a Complex128Array... +{ + const zx = new Complex128Array( 10 ); + + zdscal( zx.length, 2.0, 10, 1 ); // $ExpectError + zdscal( zx.length, 2.0, '10', 1 ); // $ExpectError + zdscal( zx.length, 2.0, true, 1 ); // $ExpectError + zdscal( zx.length, 2.0, false, 1 ); // $ExpectError + zdscal( zx.length, 2.0, null, 1 ); // $ExpectError + zdscal( zx.length, 2.0, undefined, 1 ); // $ExpectError + zdscal( zx.length, 2.0, [ '1' ], 1 ); // $ExpectError + zdscal( zx.length, 2.0, {}, 1 ); // $ExpectError + zdscal( zx.length, 2.0, ( zx: number ): number => zx, 1 ); // $ExpectError +} + +// The compiler throws an error if the function is provided a fourth argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal( zx.length, 2.0, zx, '10' ); // $ExpectError + zdscal( zx.length, 2.0, zx, true ); // $ExpectError + zdscal( zx.length, 2.0, zx, false ); // $ExpectError + zdscal( zx.length, 2.0, zx, null ); // $ExpectError + zdscal( zx.length, 2.0, zx, undefined ); // $ExpectError + zdscal( zx.length, 2.0, zx, [] ); // $ExpectError + zdscal( zx.length, 2.0, zx, {} ); // $ExpectError + zdscal( zx.length, 2.0, zx, ( zx: number ): number => zx ); // $ExpectError +} + +// The compiler throws an error if the function is provided an unsupported number of arguments... +{ + const zx = new Complex128Array( 10 ); + + zdscal(); // $ExpectError + zdscal( zx.length ); // $ExpectError + zdscal( zx.length, 2.0 ); // $ExpectError + zdscal( zx.length, 2.0, zx ); // $ExpectError + zdscal( zx.length, 2.0, zx, 1, 10 ); // $ExpectError +} + +// Attached to main export is an `ndarray` method which returns a Complex128Array... +{ + const zx = new Complex128Array( 10 ); + + zdscal.ndarray( zx.length, 2.0, zx, 1, 0 ); // $ExpectType Complex128Array +} + +// The compiler throws an error if the `ndarray` method is provided a first argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal.ndarray( '10', 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( true, 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( false, 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( null, 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( undefined, 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( [], 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( {}, 2.0, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( ( zx: number ): number => zx, 2.0, zx, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the `ndarray` method is provided a second argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal.ndarray( zx.length, new Complex128( 1.0, 2.0 ), zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, '10', zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, true, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, false, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, null, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, undefined, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, [ '1' ], zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, {}, zx, 1, 0 ); // $ExpectError + zdscal.ndarray( zx.length, ( zx: number ): number => zx, zx, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the `ndarray` method is provided a third argument which is not a Complex128Array... +{ + const zx = new Complex128Array( 10 ); + + zdscal( zx.length, 2.0, 10, 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, '10', 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, true, 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, false, 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, null, 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, undefined, 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, [ '1' ], 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, {}, 1, 0 ); // $ExpectError + zdscal( zx.length, 2.0, ( zx: number ): number => zx, 1, 0 ); // $ExpectError +} + +// The compiler throws an error if the `ndarray` method is provided a fourth argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal.ndarray( zx.length, 2.0, zx, '10', 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, true, 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, false, 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, null, 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, undefined, 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, [], 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, {}, 0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, ( zx: number ): number => zx, 0 ); // $ExpectError +} + +// The compiler throws an error if the `ndarray` method is provided a fifth argument which is not a number... +{ + const zx = new Complex128Array( 10 ); + + zdscal.ndarray( zx.length, 2.0, zx, 1, '10' ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, true ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, false ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, null ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, undefined ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, [] ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, {} ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, ( zx: number ): number => zx ); // $ExpectError +} + +// The compiler throws an error if the `ndarray` method is provided an unsupported number of arguments... +{ + const zx = new Complex128Array( 10 ); + + zdscal.ndarray(); // $ExpectError + zdscal.ndarray( zx.length ); // $ExpectError + zdscal.ndarray( zx.length, 2.0 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1 ); // $ExpectError + zdscal.ndarray( zx.length, 2.0, zx, 1, 0, 10 ); // $ExpectError +} diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/examples/index.js b/lib/node_modules/@stdlib/blas/base/zdscal/examples/index.js new file mode 100644 index 000000000000..86e6529bb69e --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/examples/index.js @@ -0,0 +1,34 @@ +/** +* @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'; + +var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ); +var filledarrayBy = require( '@stdlib/array/filled-by' ); +var Complex128 = require( '@stdlib/complex/float64/ctor' ); +var zdscal = require( './../lib' ); + +function rand() { + return new Complex128( discreteUniform( 0, 10 ), discreteUniform( -5, 5 ) ); +} + +var zx = filledarrayBy( 10, 'complex128', rand ); +console.log( zx.toString() ); + +zdscal( zx.length, 2.0, zx, 1 ); +console.log( zx.toString() ); diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/lib/index.js b/lib/node_modules/@stdlib/blas/base/zdscal/lib/index.js new file mode 100644 index 000000000000..bed34c7d314b --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/lib/index.js @@ -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. +*/ + +'use strict'; + +/** +* BLAS level 1 routine to scale a double-precision complex floating-point vector by a double-precision floating-point constant. +* +* @module @stdlib/blas/base/zdscal +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var real = require( '@stdlib/complex/float64/real' ); +* var imag = require( '@stdlib/complex/float64/imag' ); +* var zdscal = require( '@stdlib/blas/base/zdscal' ); +* +* var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* zdscal( 3, 2.0, zx, 1 ); +* +* var z = zx.get( 0 ); +* // returns +* +* var re = real( z ); +* // returns -2.0 +* +* var im = imag( z ); +* // returns 6.0 +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var real = require( '@stdlib/complex/float64/real' ); +* var imag = require( '@stdlib/complex/float64/imag' ); +* var zdscal = require( '@stdlib/blas/base/zdscal' ); +* +* var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* zdscal.ndarray( 3, 2.0, zx, 1, 0 ); +* +* var z = zx.get( 0 ); +* // returns +* +* var re = real( z ); +* // returns -2.0 +* +* var im = imag( z ); +* // returns 6.0 +*/ + +// MODULES // + +var join = require( 'path' ).join; +var tryRequire = require( '@stdlib/utils/try-require' ); +var isError = require( '@stdlib/assert/is-error' ); +var main = require( './main.js' ); + + +// MAIN // + +var zdscal; +var tmp = tryRequire( join( __dirname, './native.js' ) ); +if ( isError( tmp ) ) { + zdscal = main; +} else { + zdscal = tmp; +} + + +// EXPORTS // + +module.exports = zdscal; + +// exports: { "ndarray": "zdscal.ndarray" } diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/lib/main.js b/lib/node_modules/@stdlib/blas/base/zdscal/lib/main.js new file mode 100644 index 000000000000..2d88da0211e0 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/lib/main.js @@ -0,0 +1,35 @@ +/** +* @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 setReadOnly = require( '@stdlib/utils/define-nonenumerable-read-only-property' ); +var zdscal = require( './zdscal.js' ); +var ndarray = require( './ndarray.js' ); + + +// MAIN // + +setReadOnly( zdscal, 'ndarray', ndarray ); + + +// EXPORTS // + +module.exports = zdscal; diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/lib/ndarray.js b/lib/node_modules/@stdlib/blas/base/zdscal/lib/ndarray.js new file mode 100644 index 000000000000..37182fe629d5 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/lib/ndarray.js @@ -0,0 +1,84 @@ +/** +* @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 reinterpret = require( '@stdlib/strided/base/reinterpret-complex128' ); + + +// MAIN // + +/** +* Scales a double-precision complex floating-point vector by a double-precision floating-point constant. +* +* @param {PositiveInteger} N - number of indexed elements +* @param {number} da - constant +* @param {Complex128Array} zx - input array +* @param {integer} strideZX - `zx` stride length +* @param {NonNegativeInteger} offsetZX - starting `zx` index +* @returns {Complex128Array} input array +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var Complex128 = require( '@stdlib/complex/float64/ctor' ); +* var real = require( '@stdlib/complex/float64/real' ); +* var imag = require( '@stdlib/complex/float64/imag' ); +* +* var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* zdscal( 3, 2.0, zx, 1, 0 ); +* +* var z = zx.get( 0 ); +* // returns +* +* var re = real( z ); +* // returns 2.0 +* +* var im = imag( z ); +* // returns 4.0 +*/ +function zdscal( N, da, zx, strideZX, offsetZX ) { + var zx64; + var ix; + var sx; + var i; + + if ( N <= 0 || da === 1.0 ) { + return zx; + } + // Reinterpret the input array as a real-valued array of interleaved real and imaginary components: + zx64 = reinterpret( zx, 0 ); + + // Adjust the stride and offset accordingly: + ix = offsetZX * 2; + sx = strideZX * 2; + + for ( i = 0; i < N; i++ ) { + zx64[ ix ] *= da; + zx64[ ix+1 ] *= da; + ix += sx; + } + return zx; +} + + +// EXPORTS // + +module.exports = zdscal; diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/lib/zdscal.js b/lib/node_modules/@stdlib/blas/base/zdscal/lib/zdscal.js new file mode 100644 index 000000000000..c68df863272d --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/lib/zdscal.js @@ -0,0 +1,63 @@ +/** +* @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 stride2offset = require( '@stdlib/strided/base/stride2offset' ); +var ndarray = require( './ndarray.js' ); + + +// MAIN // + +/** +* Scales a double-precision complex floating-point vector by a double-precision floating-point constant. +* +* @param {PositiveInteger} N - number of indexed elements +* @param {number} da - constant +* @param {Complex128Array} zx - input array +* @param {integer} strideZX - `zx` stride length +* @returns {Complex128Array} input array +* +* @example +* var Complex128Array = require( '@stdlib/array/complex128' ); +* var real = require( '@stdlib/complex/float64/real' ); +* var imag = require( '@stdlib/complex/float64/imag' ); +* +* var zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] ); +* +* zdscal( 3, 2.0, zx, 1 ); +* +* var z = zx.get( 0 ); +* // returns +* +* var re = real( z ); +* // returns 2.0 +* +* var im = imag( z ); +* // returns 4.0 +*/ +function zdscal( N, da, zx, strideZX ) { + return ndarray( N, da, zx, strideZX, stride2offset( N, strideZX ) ); +} + + +// EXPORTS // + +module.exports = zdscal; diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/package.json b/lib/node_modules/@stdlib/blas/base/zdscal/package.json new file mode 100644 index 000000000000..2107fd81e8c7 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/package.json @@ -0,0 +1,77 @@ +{ + "name": "@stdlib/blas/base/zdscal", + "version": "0.0.0", + "description": "Scale a double-precision complex floating-point vector by a double-precision floating-point constant.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "browser": "./lib/main.js", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "stdmath", + "mathematics", + "math", + "blas", + "level 1", + "linear", + "algebra", + "subroutines", + "zdscal", + "scale", + "vector", + "typed", + "array", + "ndarray", + "complex", + "complex128", + "double", + "float64", + "float64array" + ], + "__stdlib__": { + "wasm": false + } +} diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/test/test.js b/lib/node_modules/@stdlib/blas/base/zdscal/test/test.js new file mode 100644 index 000000000000..67ccee99c8a3 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/test/test.js @@ -0,0 +1,82 @@ +/** +* @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 tape = require( 'tape' ); +var proxyquire = require( 'proxyquire' ); +var isBrowser = require( '@stdlib/assert/is-browser' ); +var zdscal = require( './../lib' ); + + +// VARIABLES // + +var opts = { + 'skip': isBrowser +}; + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof zdscal, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'attached to the main export is a method providing an ndarray interface', function test( t ) { + t.strictEqual( typeof zdscal.ndarray, 'function', 'method is a function' ); + t.end(); +}); + +tape( 'if a native implementation is available, the main export is the native implementation', opts, function test( t ) { + var zdscal = proxyquire( './../lib', { + '@stdlib/utils/try-require': tryRequire + }); + + t.strictEqual( zdscal, mock, 'returns native implementation' ); + t.end(); + + function tryRequire() { + return mock; + } + + function mock() { + // Mock... + } +}); + +tape( 'if a native implementation is not available, the main export is a JavaScript implementation', opts, function test( t ) { + var zdscal; + var main; + + main = require( './../lib/zdscal.js' ); + + zdscal = proxyquire( './../lib', { + '@stdlib/utils/try-require': tryRequire + }); + + t.strictEqual( zdscal, main, 'returns JavaScript implementation' ); + t.end(); + + function tryRequire() { + return new Error( 'Cannot find module' ); + } +}); diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/test/test.ndarray.js b/lib/node_modules/@stdlib/blas/base/zdscal/test/test.ndarray.js new file mode 100644 index 000000000000..c8e16e0b6450 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/test/test.ndarray.js @@ -0,0 +1,267 @@ +/** +* @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 tape = require( 'tape' ); +var isSameComplex128Array = require( '@stdlib/assert/is-same-complex128array' ); +var Complex128Array = require( '@stdlib/array/complex128' ); +var zdscal = require( './../lib/ndarray.js' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof zdscal, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function has an arity of 5', function test( t ) { + t.strictEqual( zdscal.length, 5, 'arity of 5' ); + t.end(); +}); + +tape( 'the function scales elements from `zx` by `da`', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.3, // 1 + 0.1, // 1 + 0.5, // 2 + 0.0, // 2 + 0.0, // 3 + 0.5, // 3 + 0.0, // 4 + 0.2, // 4 + 2.0, + 3.0, + 2.0, + 3.0 + ]); + + zdscal( 4, 2.0, zx, 1, 0 ); + + expected = new Complex128Array([ + 0.6, // 1 + 0.2, // 1 + 1.0, // 2 + 0.0, // 2 + 0.0, // 3 + 1.0, // 3 + 0.0, // 4 + 0.4, // 4 + 2.0, + 3.0, + 2.0, + 3.0 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function supports a `zx` stride', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.1, // 1 + 0.1, // 1 + 3.0, + 6.0, + -0.6, // 2 + 0.1, // 2 + 4.0, + 7.0, + 0.1, // 3 + -0.3, // 3 + 7.0, + 2.0 + ]); + + zdscal( 3, 2.0, zx, 2, 0 ); + + expected = new Complex128Array([ + 0.2, // 1 + 0.2, // 1 + 3.0, + 6.0, + -1.2, // 2 + 0.2, // 2 + 4.0, + 7.0, + 0.2, // 3 + -0.6, // 3 + 7.0, + 2.0 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function supports a negative `zx` stride', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.1, // 3 + 0.1, // 3 + 3.0, + 6.0, + -0.6, // 2 + 0.1, // 2 + 4.0, + 7.0, + 0.1, // 1 + -0.3, // 1 + 7.0, + 2.0 + ]); + + zdscal( 3, 2.0, zx, -2, 4 ); + + expected = new Complex128Array([ + 0.2, // 3 + 0.2, // 3 + 3.0, + 6.0, + -1.2, // 2 + 0.2, // 2 + 4.0, + 7.0, + 0.2, // 1 + -0.6, // 1 + 7.0, + 2.0 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function supports a `zx` offset', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.1, + 0.1, + 3.0, + 6.0, + -0.6, + 0.1, + 4.0, // 1 + 6.0, // 1 + 0.1, // 2 + -0.3, // 2 + 7.0, // 3 + 2.0 // 3 + ]); + + zdscal( 3, 2.0, zx, 1, 3 ); + + expected = new Complex128Array([ + 0.1, + 0.1, + 3.0, + 6.0, + -0.6, + 0.1, + 8.0, // 1 + 12.0, // 1 + 0.2, // 2 + -0.6, // 2 + 14.0, // 3 + 4.0 // 3 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns a reference to the input array', function test( t ) { + var out; + var zx; + + zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + out = zdscal( 4, 2.0, zx, 1, 0 ); + + t.strictEqual( out, zx, 'same reference' ); + t.end(); +}); + +tape( 'if provided an `N` parameter less than or equal to `0`, the function returns the input array unchanged', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + + expected = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); // eslint-disable-line max-len + + zdscal( -1, 2.0, zx, 1, 0 ); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + + zdscal( 0, 2.0, zx, 1, 0 ); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function supports complex access patterns', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.1, + 0.1, + 3.0, + 6.0, + -0.6, + 0.1, + 4.0, // 2 + 6.0, // 2 + 0.1, + -0.3, + 7.0, + 2.0, + 2.0, // 1 + 3.0 // 1 + ]); + + zdscal( 2, 2.0, zx, -3, 6 ); + + expected = new Complex128Array([ + 0.1, + 0.1, + 3.0, + 6.0, + -0.6, + 0.1, + 8.0, // 2 + 12.0, // 2 + 0.1, + -0.3, + 7.0, + 2.0, + 4.0, // 1 + 6.0 // 1 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/blas/base/zdscal/test/test.zdscal.js b/lib/node_modules/@stdlib/blas/base/zdscal/test/test.zdscal.js new file mode 100644 index 000000000000..dd012578436b --- /dev/null +++ b/lib/node_modules/@stdlib/blas/base/zdscal/test/test.zdscal.js @@ -0,0 +1,217 @@ +/** +* @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 tape = require( 'tape' ); +var isSameComplex128Array = require( '@stdlib/assert/is-same-complex128array' ); +var Complex128Array = require( '@stdlib/array/complex128' ); +var zdscal = require( './../lib/zdscal.js' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof zdscal, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function has an arity of 4', function test( t ) { + t.strictEqual( zdscal.length, 4, 'arity of 4' ); + t.end(); +}); + +tape( 'the function scales elements from `zx` by `da`', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.3, // 1 + 0.1, // 1 + 0.5, // 2 + 0.0, // 2 + 0.0, // 3 + 0.5, // 3 + 0.0, // 4 + 0.2 // 4 + ]); + + zdscal( 4, 2.0, zx, 1 ); + + expected = new Complex128Array([ + 0.6, // 1 + 0.2, // 1 + 1.0, // 2 + 0.0, // 2 + 0.0, // 3 + 1.0, // 3 + 0.0, // 4 + 0.4 // 4 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function supports a `zx` stride', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.1, // 1 + 0.1, // 1 + 3.0, + 6.0, + -0.6, // 2 + 0.1, // 2 + 4.0, + 7.0, + 0.1, // 3 + -0.3, // 3 + 7.0, + 2.0 + ]); + + zdscal( 3, 2.0, zx, 2 ); + + expected = new Complex128Array([ + 0.2, // 1 + 0.2, // 1 + 3.0, + 6.0, + -1.2, // 2 + 0.2, // 2 + 4.0, + 7.0, + 0.2, // 3 + -0.6, // 3 + 7.0, + 2.0 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function supports a negative `zx` stride', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array([ + 0.1, // 3 + 0.1, // 3 + 3.0, + 6.0, + -0.6, // 2 + 0.1, // 2 + 4.0, + 7.0, + 0.1, // 1 + -0.3, // 1 + 7.0, + 2.0 + ]); + + zdscal( 3, 2.0, zx, -2 ); + + expected = new Complex128Array([ + 0.2, // 3 + 0.2, // 3 + 3.0, + 6.0, + -1.2, // 2 + 0.2, // 2 + 4.0, + 7.0, + 0.2, // 1 + -0.6, // 1 + 7.0, + 2.0 + ]); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns a reference to the input array', function test( t ) { + var out; + var zx; + + zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + out = zdscal( 4, 2.0, zx, 1 ); + + t.strictEqual( out, zx, 'same reference' ); + t.end(); +}); + +tape( 'if provided an `N` parameter less than or equal to `0`, the function returns the input array unchanged', function test( t ) { + var expected; + var zx; + + zx = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); + + expected = new Complex128Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 ] ); // eslint-disable-line max-len + + zdscal( -1, 2.0, zx, 1 ); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + + zdscal( 0, 2.0, zx, 1 ); + t.strictEqual( isSameComplex128Array( zx, expected ), true, 'returns expected value' ); + + t.end(); +}); + +tape( 'the function supports view offsets', function test( t ) { + var expected; + var zx0; + var zx1; + + // Initial array: + zx0 = new Complex128Array([ + 0.1, + -0.3, + 8.0, // 1 + 9.0, // 1 + 0.5, // 2 + -0.1, // 2 + 2.0, // 3 + 5.0, // 3 + 2.0, + 3.0 + ]); + + // Create offset view: + zx1 = new Complex128Array( zx0.buffer, zx0.BYTES_PER_ELEMENT*1 ); // begin at 2nd element + + zdscal( 3, 2.0, zx1, 1 ); + + expected = new Complex128Array([ + 0.1, + -0.3, + 16.0, // 1 + 18.0, // 1 + 1.0, // 2 + -0.2, // 2 + 4.0, // 3 + 10.0, // 3 + 2.0, + 3.0 + ]); + t.strictEqual( isSameComplex128Array( zx0, expected ), true, 'returns expected value' ); + t.end(); +}); diff --git a/lib/node_modules/@stdlib/blas/ext/base/README.md b/lib/node_modules/@stdlib/blas/ext/base/README.md index 3d13ca4e0660..1ee952c9ebd3 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/README.md +++ b/lib/node_modules/@stdlib/blas/ext/base/README.md @@ -86,30 +86,30 @@ var ns = extblas; - [`dssumpw( N, x, strideX )`][@stdlib/blas/ext/base/dssumpw]: calculate the sum of single-precision floating-point strided array elements using pairwise summation with extended accumulation and returning an extended precision result. - [`dsum( N, x, strideX )`][@stdlib/blas/ext/base/dsum]: calculate the sum of double-precision floating-point strided array elements. - [`dsumkbn( N, x, strideX )`][@stdlib/blas/ext/base/dsumkbn]: calculate the sum of double-precision floating-point strided array elements using an improved Kahan–Babuška algorithm. -- [`dsumkbn2( N, x, stride )`][@stdlib/blas/ext/base/dsumkbn2]: calculate the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. -- [`dsumors( N, x, stride )`][@stdlib/blas/ext/base/dsumors]: calculate the sum of double-precision floating-point strided array elements using ordinary recursive summation. -- [`dsumpw( N, x, stride )`][@stdlib/blas/ext/base/dsumpw]: calculate the sum of double-precision floating-point strided array elements using pairwise summation. -- [`gapx( N, alpha, x, stride )`][@stdlib/blas/ext/base/gapx]: add a constant to each element in a strided array. -- [`gapxsum( N, alpha, x, stride )`][@stdlib/blas/ext/base/gapxsum]: add a constant to each strided array element and compute the sum. -- [`gapxsumkbn( N, alpha, x, stride )`][@stdlib/blas/ext/base/gapxsumkbn]: add a constant to each strided array element and compute the sum using an improved Kahan–Babuška algorithm. -- [`gapxsumkbn2( N, alpha, x, stride )`][@stdlib/blas/ext/base/gapxsumkbn2]: add a constant to each strided array element and compute the sum using a second-order iterative Kahan–Babuška algorithm. -- [`gapxsumors( N, alpha, x, stride )`][@stdlib/blas/ext/base/gapxsumors]: add a constant to each strided array element and compute the sum using ordinary recursive summation. -- [`gapxsumpw( N, alpha, x, stride )`][@stdlib/blas/ext/base/gapxsumpw]: add a constant to each strided array element and compute the sum using pairwise summation. -- [`gasumpw( N, x, stride )`][@stdlib/blas/ext/base/gasumpw]: calculate the sum of absolute values (_L1_ norm) of strided array elements using pairwise summation. +- [`dsumkbn2( N, x, strideX )`][@stdlib/blas/ext/base/dsumkbn2]: calculate the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. +- [`dsumors( N, x, strideX )`][@stdlib/blas/ext/base/dsumors]: calculate the sum of double-precision floating-point strided array elements using ordinary recursive summation. +- [`dsumpw( N, x, strideX )`][@stdlib/blas/ext/base/dsumpw]: calculate the sum of double-precision floating-point strided array elements using pairwise summation. +- [`gapx( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gapx]: add a scalar constant to each element in a strided array. +- [`gapxsum( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gapxsum]: add a scalar constant to each strided array element and compute the sum. +- [`gapxsumkbn( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gapxsumkbn]: add a scalar constant to each strided array element and compute the sum using an improved Kahan–Babuška algorithm. +- [`gapxsumkbn2( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gapxsumkbn2]: add a scalar constant to each strided array element and compute the sum using a second-order iterative Kahan–Babuška algorithm. +- [`gapxsumors( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gapxsumors]: add a scalar constant to each strided array element and compute the sum using ordinary recursive summation. +- [`gapxsumpw( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gapxsumpw]: add a scalar constant to each strided array element and compute the sum using pairwise summation. +- [`gasumpw( N, x, strideX )`][@stdlib/blas/ext/base/gasumpw]: calculate the sum of absolute values (_L1_ norm) of strided array elements using pairwise summation. - [`gcusum( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gcusum]: calculate the cumulative sum of strided array elements. - [`gcusumkbn( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gcusumkbn]: calculate the cumulative sum of strided array elements using an improved Kahan–Babuška algorithm. - [`gcusumkbn2( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gcusumkbn2]: calculate the cumulative sum of strided array elements using a second-order iterative Kahan–Babuška algorithm. - [`gcusumors( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gcusumors]: calculate the cumulative sum of strided array elements using ordinary recursive summation. - [`gcusumpw( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gcusumpw]: calculate the cumulative sum of strided array elements using pairwise summation. -- [`gfillBy( N, x, stride, clbk[, thisArg] )`][@stdlib/blas/ext/base/gfill-by]: fill a strided array according to a provided callback function. -- [`gfill( N, alpha, x, stride )`][@stdlib/blas/ext/base/gfill]: fill a strided array with a specified scalar constant. +- [`gfillBy( N, x, strideX, clbk[, thisArg] )`][@stdlib/blas/ext/base/gfill-by]: fill a strided array according to a provided callback function. +- [`gfill( N, alpha, x, strideX )`][@stdlib/blas/ext/base/gfill]: fill a strided array with a specified scalar constant. - [`gnannsumkbn( N, x, strideX, out, strideOut )`][@stdlib/blas/ext/base/gnannsumkbn]: calculate the sum of strided array elements, ignoring `NaN` values and using an improved Kahan–Babuška algorithm. -- [`gnansum( N, x, stride )`][@stdlib/blas/ext/base/gnansum]: calculate the sum of strided array elements, ignoring `NaN` values. -- [`gnansumkbn( N, x, stride )`][@stdlib/blas/ext/base/gnansumkbn]: calculate the sum of strided array elements, ignoring `NaN` values and using an improved Kahan–Babuška algorithm. -- [`gnansumkbn2( N, x, stride )`][@stdlib/blas/ext/base/gnansumkbn2]: calculate the sum of strided array elements, ignoring `NaN` values and using a second-order iterative Kahan–Babuška algorithm. -- [`gnansumors( N, x, stride )`][@stdlib/blas/ext/base/gnansumors]: calculate the sum of strided array elements, ignoring `NaN` values and using ordinary recursive summation. -- [`gnansumpw( N, x, stride )`][@stdlib/blas/ext/base/gnansumpw]: calculate the sum of strided array elements, ignoring `NaN` values and using pairwise summation. -- [`grev( N, x, stride )`][@stdlib/blas/ext/base/grev]: reverse a strided array in-place. +- [`gnansum( N, x, strideX )`][@stdlib/blas/ext/base/gnansum]: calculate the sum of strided array elements, ignoring `NaN` values. +- [`gnansumkbn( N, x, strideX )`][@stdlib/blas/ext/base/gnansumkbn]: calculate the sum of strided array elements, ignoring `NaN` values and using an improved Kahan–Babuška algorithm. +- [`gnansumkbn2( N, x, strideX )`][@stdlib/blas/ext/base/gnansumkbn2]: calculate the sum of strided array elements, ignoring `NaN` values and using a second-order iterative Kahan–Babuška algorithm. +- [`gnansumors( N, x, strideX )`][@stdlib/blas/ext/base/gnansumors]: calculate the sum of strided array elements, ignoring `NaN` values and using ordinary recursive summation. +- [`gnansumpw( N, x, strideX )`][@stdlib/blas/ext/base/gnansumpw]: calculate the sum of strided array elements, ignoring `NaN` values and using pairwise summation. +- [`grev( N, x, strideX )`][@stdlib/blas/ext/base/grev]: reverse a strided array in-place. - [`gsort2hp( N, order, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gsort2hp]: simultaneously sort two strided arrays based on the sort order of the first array using heapsort. - [`gsort2ins( N, order, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gsort2ins]: simultaneously sort two strided arrays based on the sort order of the first array using insertion sort. - [`gsort2sh( N, order, x, strideX, y, strideY )`][@stdlib/blas/ext/base/gsort2sh]: simultaneously sort two strided arrays based on the sort order of the first array using Shellsort. @@ -117,17 +117,17 @@ var ns = extblas; - [`gsortins( N, order, x, stride )`][@stdlib/blas/ext/base/gsortins]: sort a strided array using insertion sort. - [`gsortsh( N, order, x, stride )`][@stdlib/blas/ext/base/gsortsh]: sort a strided array using Shellsort. - [`gsum( N, x, stride )`][@stdlib/blas/ext/base/gsum]: calculate the sum of strided array elements. -- [`gsumkbn( N, x, stride )`][@stdlib/blas/ext/base/gsumkbn]: calculate the sum of strided array elements using an improved Kahan–Babuška algorithm. -- [`gsumkbn2( N, x, stride )`][@stdlib/blas/ext/base/gsumkbn2]: calculate the sum of strided array elements using a second-order iterative Kahan–Babuška algorithm. -- [`gsumors( N, x, stride )`][@stdlib/blas/ext/base/gsumors]: calculate the sum of strided array elements using ordinary recursive summation. -- [`gsumpw( N, x, stride )`][@stdlib/blas/ext/base/gsumpw]: calculate the sum of strided array elements using pairwise summation. -- [`sapx( N, alpha, x, stride )`][@stdlib/blas/ext/base/sapx]: add a constant to each element in a single-precision floating-point strided array. -- [`sapxsum( N, alpha, x, stride )`][@stdlib/blas/ext/base/sapxsum]: add a constant to each single-precision floating-point strided array element and compute the sum. -- [`sapxsumkbn( N, alpha, x, stride )`][@stdlib/blas/ext/base/sapxsumkbn]: add a constant to each single-precision floating-point strided array element and compute the sum using an improved Kahan–Babuška algorithm. -- [`sapxsumkbn2( N, alpha, x, stride )`][@stdlib/blas/ext/base/sapxsumkbn2]: add a constant to each single-precision floating-point strided array element and compute the sum using a second-order iterative Kahan–Babuška algorithm. -- [`sapxsumors( N, alpha, x, stride )`][@stdlib/blas/ext/base/sapxsumors]: add a constant to each single-precision floating-point strided array element and compute the sum using ordinary recursive summation. -- [`sapxsumpw( N, alpha, x, stride )`][@stdlib/blas/ext/base/sapxsumpw]: add a constant to each single-precision floating-point strided array element and compute the sum using pairwise summation. -- [`sasumpw( N, x, stride )`][@stdlib/blas/ext/base/sasumpw]: calculate the sum of absolute values (_L1_ norm) of single-precision floating-point strided array elements using pairwise summation. +- [`gsumkbn( N, x, strideX )`][@stdlib/blas/ext/base/gsumkbn]: calculate the sum of strided array elements using an improved Kahan–Babuška algorithm. +- [`gsumkbn2( N, x, strideX )`][@stdlib/blas/ext/base/gsumkbn2]: calculate the sum of strided array elements using a second-order iterative Kahan–Babuška algorithm. +- [`gsumors( N, x, strideX )`][@stdlib/blas/ext/base/gsumors]: calculate the sum of strided array elements using ordinary recursive summation. +- [`gsumpw( N, x, strideX )`][@stdlib/blas/ext/base/gsumpw]: calculate the sum of strided array elements using pairwise summation. +- [`sapx( N, alpha, x, strideX )`][@stdlib/blas/ext/base/sapx]: add a scalar constant to each element in a single-precision floating-point strided array. +- [`sapxsum( N, alpha, x, strideX )`][@stdlib/blas/ext/base/sapxsum]: add a scalar constant to each single-precision floating-point strided array element and compute the sum. +- [`sapxsumkbn( N, alpha, x, strideX )`][@stdlib/blas/ext/base/sapxsumkbn]: add a scalar constant to each single-precision floating-point strided array element and compute the sum using an improved Kahan–Babuška algorithm. +- [`sapxsumkbn2( N, alpha, x, strideX )`][@stdlib/blas/ext/base/sapxsumkbn2]: add a scalar constant to each single-precision floating-point strided array element and compute the sum using a second-order iterative Kahan–Babuška algorithm. +- [`sapxsumors( N, alpha, x, strideX )`][@stdlib/blas/ext/base/sapxsumors]: add a scalar constant to each single-precision floating-point strided array element and compute the sum using ordinary recursive summation. +- [`sapxsumpw( N, alpha, x, strideX )`][@stdlib/blas/ext/base/sapxsumpw]: add a scalar constant to each single-precision floating-point strided array element and compute the sum using pairwise summation. +- [`sasumpw( N, x, strideX )`][@stdlib/blas/ext/base/sasumpw]: calculate the sum of absolute values (_L1_ norm) of single-precision floating-point strided array elements using pairwise summation. - [`scusum( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/scusum]: calculate the cumulative sum of single-precision floating-point strided array elements. - [`scusumkbn( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/scusumkbn]: calculate the cumulative sum of single-precision floating-point strided array elements using an improved Kahan–Babuška algorithm. - [`scusumkbn2( N, sum, x, strideX, y, strideY )`][@stdlib/blas/ext/base/scusumkbn2]: calculate the cumulative sum of single-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/README.md b/lib/node_modules/@stdlib/blas/ext/base/dapx/README.md index f0a97cb8c937..c6a3afbd39f4 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/README.md +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/README.md @@ -48,7 +48,7 @@ The function has the following parameters: - **N**: number of indexed elements. - **alpha**: scalar constant. - **x**: input [`Float64Array`][@stdlib/array/float64]. -- **strideX**: stride length for `x`. +- **strideX**: stride length. The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to add a constant to every other element: @@ -168,14 +168,14 @@ console.log( x ); #include "stdlib/blas/ext/base/dapx.h" ``` -#### c_dapx( N, alpha, \*X, strideX ) +#### stdlib_strided_dapx( N, alpha, \*X, strideX ) Adds a scalar constant to each element in a double-precision floating-point strided array. ```c double x[] = { 1.0, 2.0, 3.0, 4.0 }; -c_dapx( 4, 5.0, x, 1 ); +stdlib_strided_dapx( 4, 5.0, x, 1 ); ``` @@ -187,17 +187,17 @@ The function accepts the following arguments: - **strideX**: `[in] CBLAS_INT` stride length for `X`. ```c -void c_dapx( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX ); +void stdlib_strided_dapx( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX ); ``` -#### c_dapx_ndarray( N, alpha, \*X, strideX, offsetX ) +#### stdlib_strided_dapx_ndarray( N, alpha, \*X, strideX, offsetX ) Adds a scalar constant to each element in a double-precision floating-point strided array using alternative indexing semantics. ```c double x[] = { 1.0, 2.0, 3.0, 4.0 }; -c_dapx_ndarray( 4, 5.0, x, 1, 0 ); +stdlib_strided_dapx_ndarray( 4, 5.0, x, 1, 0 ); ``` The function accepts the following arguments: @@ -205,11 +205,11 @@ The function accepts the following arguments: - **N**: `[in] CBLAS_INT` number of indexed elements. - **alpha**: `[in] double` scalar constant. - **X**: `[inout] double*` input array. -- **strideX**: `[in] CBLAS_INT` stride length for `X`. -- **offsetX**: `[in] CBLAS_INT` starting index for `X`. +- **strideX**: `[in] CBLAS_INT` stride length. +- **offsetX**: `[in] CBLAS_INT` starting index. ```c -void c_dapx_ndarray( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); +void stdlib_strided_dapx_ndarray( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); ``` @@ -245,7 +245,7 @@ int main( void ) { const int strideX = 1; // Fill the array: - c_dapx( N, 5.0, x, strideX ); + stdlib_strided_dapx( N, 5.0, x, strideX ); // Print the result: for ( int i = 0; i < 8; i++ ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/benchmark/c/benchmark.length.c b/lib/node_modules/@stdlib/blas/ext/base/dapx/benchmark/c/benchmark.length.c index a4e9dbd372b0..678f2c5df6c1 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/benchmark/c/benchmark.length.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/benchmark/c/benchmark.length.c @@ -106,7 +106,7 @@ static double benchmark1( int iterations, int len ) { t = tic(); for ( i = 0; i < iterations; i++ ) { // cppcheck-suppress uninitvar - c_dapx( len, 5.0, x, 1 ); + stdlib_strided_dapx( len, 5.0, x, 1 ); if ( x[ 0 ] != x[ 0 ] ) { printf( "should not return NaN\n" ); break; @@ -131,7 +131,7 @@ static double benchmark2( int iterations, int len ) { t = tic(); for ( i = 0; i < iterations; i++ ) { // cppcheck-suppress uninitvar - c_dapx_ndarray( len, 5.0, x, 1, 0 ); + stdlib_strided_dapx_ndarray( len, 5.0, x, 1, 0 ); if ( x[ 0 ] != x[ 0 ] ) { printf( "should not return NaN\n" ); break; diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/examples/c/example.c b/lib/node_modules/@stdlib/blas/ext/base/dapx/examples/c/example.c index ec1ac38026ef..e77cbe0d09ba 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/examples/c/example.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/examples/c/example.c @@ -30,7 +30,7 @@ int main( void ) { const int strideX = 1; // Add a constant to each element: - c_dapx( N, 5.0, x, strideX ); + stdlib_strided_dapx( N, 5.0, x, strideX ); // Print the result: for ( int i = 0; i < 8; i++ ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/include/stdlib/blas/ext/base/dapx.h b/lib/node_modules/@stdlib/blas/ext/base/dapx/include/stdlib/blas/ext/base/dapx.h index d292078b1ca3..7298dbee5a8f 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/include/stdlib/blas/ext/base/dapx.h +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/include/stdlib/blas/ext/base/dapx.h @@ -31,12 +31,12 @@ extern "C" { /** * Adds a scalar constant to each element in a double-precision floating-point strided array. */ -void API_SUFFIX(c_dapx)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX ); +void API_SUFFIX(stdlib_strided_dapx)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX ); /** * Adds a scalar constant to each element in a double-precision floating-point strided array using alternative indexing semantics. */ -void API_SUFFIX(c_dapx_ndarray)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); +void API_SUFFIX(stdlib_strided_dapx_ndarray)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); #ifdef __cplusplus } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.js b/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.js index efe6621ddb44..d13e30fd1128 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.js @@ -39,9 +39,8 @@ var M = 5; * var Float64Array = require( '@stdlib/array/float64' ); * * var x = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] ); -* var alpha = 5.0; * -* dapx( 3, alpha, x, 1, x.length-3 ); +* dapx( 3, 5.0, x, 1, x.length-3 ); * // x => [ 1.0, -2.0, 3.0, 1.0, 10.0, -1.0 ] */ function dapx( N, alpha, x, strideX, offsetX ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.native.js b/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.native.js index f743b6fac10a..c9291a1a3c20 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/lib/ndarray.native.js @@ -39,9 +39,8 @@ var addon = require( './../src/addon.node' ); * var Float64Array = require( '@stdlib/array/float64' ); * * var x = new Float64Array( [ 1.0, -2.0, 3.0, -4.0, 5.0, -6.0 ] ); -* var alpha = 5.0; * -* dapx( 3, alpha, x, 1, x.length-3 ); +* dapx( 3, 5.0, x, 1, x.length-3 ); * // x => [ 1.0, -2.0, 3.0, 1.0, 10.0, -1.0 ] */ function dapx( N, alpha, x, strideX, offsetX ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/src/addon.c b/lib/node_modules/@stdlib/blas/ext/base/dapx/src/addon.c index 455f74e295db..88e2c6bb251c 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/src/addon.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/src/addon.c @@ -38,7 +38,7 @@ static napi_value addon( napi_env env, napi_callback_info info ) { STDLIB_NAPI_ARGV_DOUBLE( env, alpha, argv, 1 ); STDLIB_NAPI_ARGV_INT64( env, strideX, argv, 3 ); STDLIB_NAPI_ARGV_STRIDED_FLOAT64ARRAY( env, X, N, strideX, argv, 2 ); - API_SUFFIX(c_dapx)( N, alpha, X, strideX ); + API_SUFFIX(stdlib_strided_dapx)( N, alpha, X, strideX ); return NULL; } @@ -56,7 +56,7 @@ static napi_value addon_method( napi_env env, napi_callback_info info ) { STDLIB_NAPI_ARGV_INT64( env, strideX, argv, 3 ); STDLIB_NAPI_ARGV_INT64( env, offsetX, argv, 4 ); STDLIB_NAPI_ARGV_STRIDED_FLOAT64ARRAY( env, X, N, strideX, argv, 2 ); - API_SUFFIX(c_dapx_ndarray)( N, alpha, X, strideX, offsetX ); + API_SUFFIX(stdlib_strided_dapx_ndarray)( N, alpha, X, strideX, offsetX ); return NULL; } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapx/src/main.c b/lib/node_modules/@stdlib/blas/ext/base/dapx/src/main.c index 193e2fec7590..dd9e1084271b 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapx/src/main.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dapx/src/main.c @@ -28,9 +28,9 @@ * @param X input array * @param strideX stride length */ -void API_SUFFIX(c_dapx)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX ) { +void API_SUFFIX(stdlib_strided_dapx)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX ) { CBLAS_INT ox = stdlib_strided_stride2offset( N, strideX ); - API_SUFFIX(c_dapx_ndarray)( N, alpha, X, strideX, ox ); + API_SUFFIX(stdlib_strided_dapx_ndarray)( N, alpha, X, strideX, ox ); } /** @@ -42,7 +42,7 @@ void API_SUFFIX(c_dapx)( const CBLAS_INT N, const double alpha, double *X, const * @param strideX stride length * @param offsetX starting index */ -void API_SUFFIX(c_dapx_ndarray)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ) { +void API_SUFFIX(stdlib_strided_dapx_ndarray)( const CBLAS_INT N, const double alpha, double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ) { CBLAS_INT ix; CBLAS_INT m; CBLAS_INT i; diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/README.md b/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/README.md index 1b1afe9a0d9d..79234328c4e4 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/README.md +++ b/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/README.md @@ -285,7 +285,7 @@ int main( void ) { - [`@stdlib/blas/ext/base/dapxsum`][@stdlib/blas/ext/base/dapxsum]: add a scalar constant to each double-precision floating-point strided array element and compute the sum. - [`@stdlib/blas/ext/base/dsumkbn`][@stdlib/blas/ext/base/dsumkbn]: calculate the sum of double-precision floating-point strided array elements using an improved Kahan–Babuška algorithm. -- [`@stdlib/blas/ext/base/gapxsumkbn`][@stdlib/blas/ext/base/gapxsumkbn]: add a constant to each strided array element and compute the sum using an improved Kahan–Babuška algorithm. +- [`@stdlib/blas/ext/base/gapxsumkbn`][@stdlib/blas/ext/base/gapxsumkbn]: add a scalar constant to each strided array element and compute the sum using an improved Kahan–Babuška algorithm. - [`@stdlib/blas/ext/base/sapxsumkbn`][@stdlib/blas/ext/base/sapxsumkbn]: add a constant to each single-precision floating-point strided array element and compute the sum using an improved Kahan–Babuška algorithm. diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/manifest.json b/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/manifest.json index f587df37ca10..e5e1db92b9e7 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/manifest.json +++ b/lib/node_modules/@stdlib/blas/ext/base/dapxsumkbn/manifest.json @@ -79,7 +79,8 @@ "libpath": [], "dependencies": [ "@stdlib/blas/base/shared", - "@stdlib/strided/base/stride2offset" + "@stdlib/strided/base/stride2offset", + "@stdlib/math/base/special/abs" ] }, { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dapxsumors/README.md b/lib/node_modules/@stdlib/blas/ext/base/dapxsumors/README.md index 01bbc0703969..20e7f8ed63ba 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dapxsumors/README.md +++ b/lib/node_modules/@stdlib/blas/ext/base/dapxsumors/README.md @@ -280,10 +280,10 @@ int main( void ) { ## See Also -- [`@stdlib/blas/ext/base/dapxsum`][@stdlib/blas/ext/base/dapxsum]: adds a constant to each double-precision floating-point strided array element and computes the sum. +- [`@stdlib/blas/ext/base/dapxsum`][@stdlib/blas/ext/base/dapxsum]: add a scalar constant to each double-precision floating-point strided array element and compute the sum. - [`@stdlib/blas/ext/base/dsumors`][@stdlib/blas/ext/base/dsumors]: calculate the sum of double-precision floating-point strided array elements using ordinary recursive summation. -- [`@stdlib/blas/ext/base/gapxsumors`][@stdlib/blas/ext/base/gapxsumors]: adds a constant to each strided array element and computes the sum using ordinary recursive summation. -- [`@stdlib/blas/ext/base/sapxsumors`][@stdlib/blas/ext/base/sapxsumors]: adds a constant to each single-precision floating-point strided array element and computes the sum using ordinary recursive summation. +- [`@stdlib/blas/ext/base/gapxsumors`][@stdlib/blas/ext/base/gapxsumors]: add a constant to each strided array element and compute the sum using ordinary recursive summation. +- [`@stdlib/blas/ext/base/sapxsumors`][@stdlib/blas/ext/base/sapxsumors]: add a scalar constant to each single-precision floating-point strided array element and compute the sum using ordinary recursive summation. diff --git a/lib/node_modules/@stdlib/blas/ext/base/docs/types/index.d.ts b/lib/node_modules/@stdlib/blas/ext/base/docs/types/index.d.ts index f3eac464da8f..1012e374b5c1 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/blas/ext/base/docs/types/index.d.ts @@ -1370,7 +1370,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1396,7 +1396,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1422,7 +1422,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1444,12 +1444,12 @@ interface Namespace { dsumpw: typeof dsumpw; /** - * Adds a constant to each element in a strided array. + * Adds a scalar constant to each element in a strided array. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns `x` * * @example @@ -1467,12 +1467,12 @@ interface Namespace { gapx: typeof gapx; /** - * Adds a constant to each strided array element and computes the sum. + * Adds a scalar constant to each strided array element and computes the sum. * * @param N - number of indexed elements * @param alpha - constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1490,12 +1490,12 @@ interface Namespace { gapxsum: typeof gapxsum; /** - * Adds a constant to each strided array element and computes the sum using an improved Kahan–Babuška algorithm. + * Adds a scalar constant to each strided array element and computes the sum using an improved Kahan–Babuška algorithm. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1513,12 +1513,12 @@ interface Namespace { gapxsumkbn: typeof gapxsumkbn; /** - * Adds a constant to each strided array element and computes the sum using a second-order iterative Kahan–Babuška algorithm. + * Adds a scalar constant to each strided array element and computes the sum using a second-order iterative Kahan–Babuška algorithm. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1536,12 +1536,12 @@ interface Namespace { gapxsumkbn2: typeof gapxsumkbn2; /** - * Adds a constant to each strided array element and computes the sum using ordinary recursive summation. + * Adds a scalar constant to each strided array element and computes the sum using ordinary recursive summation. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1559,12 +1559,12 @@ interface Namespace { gapxsumors: typeof gapxsumors; /** - * Adds a constant to each strided array element and computes the sum using pairwise summation. + * Adds a scalar constant to each strided array element and computes the sum using pairwise summation. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1586,7 +1586,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1609,9 +1609,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -1636,9 +1636,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -1663,9 +1663,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -1690,9 +1690,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -1717,9 +1717,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -1739,12 +1739,12 @@ interface Namespace { gcusumpw: typeof gcusumpw; /** - * Fills a strided array with a specified scalar value. + * Fills a strided array with a specified scalar constant. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns `x` * * @example @@ -1777,8 +1777,8 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length - * @param clbk - callback + * @param strideX - stride length + * @param clbk - callback function * @param thisArg - execution context * @returns `x` * @@ -1809,9 +1809,9 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param out - output array whose first element is the sum and whose second element is the number of non-NaN elements - * @param strideOut - `out` stride length + * @param strideOut - stride length for `out` * @returns output array * * @example @@ -1835,7 +1835,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1857,7 +1857,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1879,7 +1879,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1901,7 +1901,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1923,7 +1923,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -1945,7 +1945,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns `x` * * @example @@ -2169,7 +2169,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2191,7 +2191,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2213,7 +2213,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2235,7 +2235,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2253,12 +2253,12 @@ interface Namespace { gsumpw: typeof gsumpw; /** - * Adds a constant to each element in a single-precision floating-point strided array. + * Adds a scalar constant to each element in a single-precision floating-point strided array. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns `x` * * @example @@ -2280,12 +2280,12 @@ interface Namespace { sapx: typeof sapx; /** - * Adds a constant to each single-precision floating-point strided array element and computes the sum. + * Adds a scalar constant to each single-precision floating-point strided array element and computes the sum. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2307,12 +2307,12 @@ interface Namespace { sapxsum: typeof sapxsum; /** - * Adds a constant to each single-precision floating-point strided array element and computes the sum using an improved Kahan–Babuška algorithm. + * Adds a scalar constant to each single-precision floating-point strided array element and computes the sum using an improved Kahan–Babuška algorithm. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2334,12 +2334,12 @@ interface Namespace { sapxsumkbn: typeof sapxsumkbn; /** - * Adds a constant to each single-precision floating-point strided array element and computes the sum using a second-order iterative Kahan–Babuška algorithm. + * Adds a scalar constant to each single-precision floating-point strided array element and computes the sum using a second-order iterative Kahan–Babuška algorithm. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2361,12 +2361,12 @@ interface Namespace { sapxsumkbn2: typeof sapxsumkbn2; /** - * Adds a constant to each single-precision floating-point strided array element and computes the sum using ordinary recursive summation. + * Adds a scalar constant to each single-precision floating-point strided array element and computes the sum using ordinary recursive summation. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2388,12 +2388,12 @@ interface Namespace { sapxsumors: typeof sapxsumors; /** - * Adds a constant to each single-precision floating-point strided array element and computes the sum using pairwise summation. + * Adds a scalar constant to each single-precision floating-point strided array element and computes the sum using pairwise summation. * * @param N - number of indexed elements - * @param alpha - constant + * @param alpha - scalar constant * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2419,7 +2419,7 @@ interface Namespace { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -2446,9 +2446,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -2477,9 +2477,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -2508,9 +2508,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -2539,9 +2539,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example @@ -2570,9 +2570,9 @@ interface Namespace { * @param N - number of indexed elements * @param sum - initial sum * @param x - input array - * @param strideX - `x` stride length + * @param strideX - stride length for `x` * @param y - output array - * @param strideY - `y` stride length + * @param strideY - stride length for `y` * @returns output array * * @example diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/README.md b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/README.md index 20ea8a24b5db..8bf197f27804 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/README.md +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/README.md @@ -36,7 +36,7 @@ limitations under the License. var dsumkbn2 = require( '@stdlib/blas/ext/base/dsumkbn2' ); ``` -#### dsumkbn2( N, x, stride ) +#### dsumkbn2( N, x, strideX ) Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. @@ -45,7 +45,7 @@ var Float64Array = require( '@stdlib/array/float64' ); var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -var v = dsumkbn2( 3, x, 1 ); +var v = dsumkbn2( x.length, x, 1 ); // returns 1.0 ``` @@ -53,9 +53,9 @@ The function has the following parameters: - **N**: number of indexed elements. - **x**: input [`Float64Array`][@stdlib/array/float64]. -- **stride**: index increment for `x`. +- **strideX**: stride length for `x`. -The `N` and `stride` parameters determine which elements in `x` are accessed at runtime. For example, to compute the sum of every other element in `x`, +The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element: ```javascript var Float64Array = require( '@stdlib/array/float64' ); @@ -80,7 +80,7 @@ var v = dsumkbn2( 4, x1, 2 ); // returns 5.0 ``` -#### dsumkbn2.ndarray( N, x, stride, offset ) +#### dsumkbn2.ndarray( N, x, strideX, offsetX ) Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm and alternative indexing semantics. @@ -89,19 +89,18 @@ var Float64Array = require( '@stdlib/array/float64' ); var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -var v = dsumkbn2.ndarray( 3, x, 1, 0 ); +var v = dsumkbn2.ndarray( x.length, x, 1, 0 ); // returns 1.0 ``` The function has the following additional parameters: -- **offset**: starting index for `x`. +- **offsetX**: starting index for `x`. -While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to calculate the sum of every other value in `x` starting from the second value +While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to calculate the sum of every other element starting from the second element: ```javascript var Float64Array = require( '@stdlib/array/float64' ); -var floor = require( '@stdlib/math/base/special/floor' ); var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); @@ -130,11 +129,12 @@ var v = dsumkbn2.ndarray( 4, x, 2, 1 ); ```javascript -var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); var dsumkbn2 = require( '@stdlib/blas/ext/base/dsumkbn2' ); -var x = filledarrayBy( 10, 'float64', discreteUniform( -100, 100 ) ); +var x = discreteUniform( 10, -100, 100, { + 'dtype': 'float64' +}); console.log( x ); var v = dsumkbn2( x.length, x, 1 ); @@ -145,8 +145,123 @@ console.log( v ); + + * * * +
+ +## C APIs + + + +
+ +
+ + + + + +
+ +### Usage + +```c +#include "stdlib/blas/ext/base/dsumkbn2.h" +``` + +#### stdlib_strided_dsumkbn2( N, \*X, strideX ) + +Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. + +```c +const double x[] = { 1.0, 2.0, 3.0, 4.0 }; + +double v = stdlib_strided_dsumkbn2( 4, x, 1 ); +// returns 10.0 +``` + +The function accepts the following arguments: + +- **N**: `[in] CBLAS_INT` number of indexed elements. +- **X**: `[in] double*` input array. +- **strideX**: `[in] CBLAS_INT` stride length for `X`. + +```c +double stdlib_strided_dsumkbn2( const CBLAS_INT N, const double *X, const CBLAS_INT strideX ); +``` + +#### stdlib_strided_dsumkbn2_ndarray( N, \*X, strideX, offsetX ) + +Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm and alternative indexing semantics. + +```c +const double x[] = { 1.0, 2.0, 3.0, 4.0 }; + +double v = stdlib_strided_dsumkbn2_ndarray( 4, x, 1, 0 ); +// returns 10.0 +``` + +The function accepts the following arguments: + +- **N**: `[in] CBLAS_INT` number of indexed elements. +- **X**: `[in] double*` input array. +- **strideX**: `[in] CBLAS_INT` stride length for `X`. +- **offsetX**: `[in] CBLAS_INT` starting index for `X`. + +```c +double stdlib_strided_dsumkbn2_ndarray( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +### Examples + +```c +#include "stdlib/blas/ext/base/dsumkbn2.h" +#include + +int main( void ) { + // Create a strided array: + const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 }; + + // Specify the number of elements: + const int N = 4; + + // Specify the stride length: + const int strideX = 2; + + // Compute the sum: + double v = stdlib_strided_dsumkbn2( N, x, strideX ); + + // Print the result: + printf( "sum: %lf\n", v ); +} +``` + +
+ + + +
+ + +
## References diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.js index 66237dbf6082..73821cb0ba02 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.js @@ -21,8 +21,7 @@ // MODULES // var bench = require( '@stdlib/bench' ); -var uniform = require( '@stdlib/random/base/uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var uniform = require( '@stdlib/random/array/uniform' ); var isnan = require( '@stdlib/math/base/assert/is-nan' ); var pow = require( '@stdlib/math/base/special/pow' ); var pkg = require( './../package.json' ).name; @@ -31,7 +30,9 @@ var dsumkbn2 = require( './../lib/dsumkbn2.js' ); // VARIABLES // -var rand = uniform( -100.0, 100.0 ); +var options = { + 'dtype': 'float64' +}; // FUNCTIONS // @@ -44,7 +45,7 @@ var rand = uniform( -100.0, 100.0 ); * @returns {Function} benchmark function */ function createBenchmark( len ) { - var x = filledarrayBy( len, 'float64', rand ); + var x = uniform( len, -100, 100, options ); return benchmark; function benchmark( b ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.native.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.native.js index 1eb8239f0d78..970f9c599d42 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.native.js @@ -22,8 +22,7 @@ var resolve = require( 'path' ).resolve; var bench = require( '@stdlib/bench' ); -var uniform = require( '@stdlib/random/base/uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var uniform = require( '@stdlib/random/array/uniform' ); var isnan = require( '@stdlib/math/base/assert/is-nan' ); var pow = require( '@stdlib/math/base/special/pow' ); var tryRequire = require( '@stdlib/utils/try-require' ); @@ -36,7 +35,9 @@ var dsumkbn2 = tryRequire( resolve( __dirname, './../lib/dsumkbn2.native.js' ) ) var opts = { 'skip': ( dsumkbn2 instanceof Error ) }; -var rand = uniform( -100.0, 100.0 ); +var options = { + 'dtype': 'float64' +}; // FUNCTIONS // @@ -49,7 +50,7 @@ var rand = uniform( -100.0, 100.0 ); * @returns {Function} benchmark function */ function createBenchmark( len ) { - var x = filledarrayBy( len, 'float64', rand ); + var x = uniform( len, -100, 100, options ); return benchmark; function benchmark( b ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.js index 88a1b89b76ed..a1140774100a 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.js @@ -21,8 +21,7 @@ // MODULES // var bench = require( '@stdlib/bench' ); -var uniform = require( '@stdlib/random/base/uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var uniform = require( '@stdlib/random/array/uniform' ); var isnan = require( '@stdlib/math/base/assert/is-nan' ); var pow = require( '@stdlib/math/base/special/pow' ); var pkg = require( './../package.json' ).name; @@ -31,7 +30,9 @@ var dsumkbn2 = require( './../lib/ndarray.js' ); // VARIABLES // -var rand = uniform( -100.0, 100.0 ); +var options = { + 'dtype': 'float64' +}; // FUNCTIONS // @@ -44,7 +45,7 @@ var rand = uniform( -100.0, 100.0 ); * @returns {Function} benchmark function */ function createBenchmark( len ) { - var x = filledarrayBy( len, 'float64', rand ); + var x = uniform( len, -100, 100, options ); return benchmark; function benchmark( b ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.native.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.native.js index b587ad2fde9b..3002f93ac258 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/benchmark.ndarray.native.js @@ -22,8 +22,7 @@ var resolve = require( 'path' ).resolve; var bench = require( '@stdlib/bench' ); -var uniform = require( '@stdlib/random/base/uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var uniform = require( '@stdlib/random/array/uniform' ); var isnan = require( '@stdlib/math/base/assert/is-nan' ); var pow = require( '@stdlib/math/base/special/pow' ); var tryRequire = require( '@stdlib/utils/try-require' ); @@ -36,7 +35,9 @@ var dsumkbn2 = tryRequire( resolve( __dirname, './../lib/ndarray.native.js' ) ); var opts = { 'skip': ( dsumkbn2 instanceof Error ) }; -var rand = uniform( -100.0, 100.0 ); +var options = { + 'dtype': 'float64' +}; // FUNCTIONS // @@ -49,7 +50,7 @@ var rand = uniform( -100.0, 100.0 ); * @returns {Function} benchmark function */ function createBenchmark( len ) { - var x = filledarrayBy( len, 'float64', rand ); + var x = uniform( len, -100, 100, options ); return benchmark; function benchmark( b ) { diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/c/benchmark.length.c b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/c/benchmark.length.c index b0f588bac5ce..af2585fe4ab4 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/c/benchmark.length.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/benchmark/c/benchmark.length.c @@ -94,7 +94,7 @@ static double rand_double( void ) { * @param len array length * @return elapsed time in seconds */ -static double benchmark( int iterations, int len ) { +static double benchmark1( int iterations, int len ) { double elapsed; double x[ len ]; double v; @@ -107,6 +107,7 @@ static double benchmark( int iterations, int len ) { v = 0.0; t = tic(); for ( i = 0; i < iterations; i++ ) { + //cppcheck-suppress uninitvar v = stdlib_strided_dsumkbn2( len, x, 1 ); if ( v != v ) { printf( "should not return NaN\n" ); @@ -120,6 +121,40 @@ static double benchmark( int iterations, int len ) { return elapsed; } +/** +* Runs a benchmark. +* +* @param iterations number of iterations +* @param len array length +* @return elapsed time in seconds +*/ +static double benchmark2( int iterations, int len ) { + double elapsed; + double x[ len ]; + double v; + double t; + int i; + + for ( i = 0; i < len; i++ ) { + x[ i ] = ( rand_double() * 20000.0 ) - 10000.0; + } + v = 0.0; + t = tic(); + for ( i = 0; i < iterations; i++ ) { + //cppcheck-suppress uninitvar + v = stdlib_strided_dsumkbn2_ndarray( len, x, 1, 0 ); + if ( v != v ) { + printf( "should not return NaN\n" ); + break; + } + } + elapsed = tic() - t; + if ( v != v ) { + printf( "should not return NaN\n" ); + } + return elapsed; +} + /** * Main execution sequence. */ @@ -142,7 +177,18 @@ int main( void ) { for ( j = 0; j < REPEATS; j++ ) { count += 1; printf( "# c::%s:len=%d\n", NAME, len ); - elapsed = benchmark( iter, len ); + elapsed = benchmark1( iter, len ); + print_results( iter, elapsed ); + printf( "ok %d benchmark finished\n", count ); + } + } + for ( i = MIN; i <= MAX; i++ ) { + len = pow( 10, i ); + iter = ITERATIONS / pow( 10, i-1 ); + for ( j = 0; j < REPEATS; j++ ) { + count += 1; + printf( "# c::%s:ndarray:len=%d\n", NAME, len ); + elapsed = benchmark2( iter, len ); print_results( iter, elapsed ); printf( "ok %d benchmark finished\n", count ); } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/repl.txt b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/repl.txt index 9f7b1409d597..ff123adf7edc 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/repl.txt +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/repl.txt @@ -1,9 +1,9 @@ -{{alias}}( N, x, stride ) +{{alias}}( N, x, strideX ) Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. - The `N` and `stride` parameters determine which elements in `x` are accessed + The `N` and stride parameters determine which elements in `x` are accessed at runtime. Indexing is relative to the first index. To introduce an offset, use a typed @@ -19,8 +19,8 @@ x: Float64Array Input array. - stride: integer - Index increment. + strideX: integer + Stride length. Returns ------- @@ -34,28 +34,25 @@ > {{alias}}( x.length, x, 1 ) 1.0 - // Using `N` and `stride` parameters: + // Using `N` and stride parameters: > x = new {{alias:@stdlib/array/float64}}( [ -2.0, 1.0, 1.0, -5.0, 2.0, -1.0 ] ); - > var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 ); - > var stride = 2; - > {{alias}}( N, x, stride ) + > {{alias}}( 3, x, 2 ) 1.0 // Using view offsets: > var x0 = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ] ); > var x1 = new {{alias:@stdlib/array/float64}}( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); - > N = {{alias:@stdlib/math/base/special/floor}}( x0.length / 2 ); - > stride = 2; - > {{alias}}( N, x1, stride ) + > {{alias}}( 3, x1, 2 ) -1.0 -{{alias}}.ndarray( N, x, stride, offset ) + +{{alias}}.ndarray( N, x, strideX, offsetX ) Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm and alternative indexing semantics. While typed array views mandate a view offset based on the underlying - buffer, the `offset` parameter supports indexing semantics based on a + buffer, the offset parameter supports indexing semantics based on a starting index. Parameters @@ -66,10 +63,10 @@ x: Float64Array Input array. - stride: integer - Index increment. + strideX: integer + Stride length. - offset: integer + offsetX: integer Starting index. Returns @@ -86,8 +83,7 @@ // Using offset parameter: > var x = new {{alias:@stdlib/array/float64}}( [ 1.0, -2.0, 3.0, 2.0, 5.0, -1.0 ] ); - > var N = {{alias:@stdlib/math/base/special/floor}}( x.length / 2 ); - > {{alias}}.ndarray( N, x, 2, 1 ) + > {{alias}}.ndarray( 3, x, 2, 1 ) -1.0 See Also diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/types/index.d.ts b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/types/index.d.ts index 9392b4f1443b..442ae97bb82e 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/types/index.d.ts +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/docs/types/index.d.ts @@ -27,7 +27,7 @@ interface Routine { * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length + * @param strideX - stride length * @returns sum * * @example @@ -38,15 +38,15 @@ interface Routine { * var v = dsumkbn2( x.length, x, 1 ); * // returns 1.0 */ - ( N: number, x: Float64Array, stride: number ): number; + ( N: number, x: Float64Array, strideX: number ): number; /** * Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm and alternative indexing semantics. * * @param N - number of indexed elements * @param x - input array - * @param stride - stride length - * @param offset - starting index + * @param strideX - stride length + * @param offsetX - starting index * @returns sum * * @example @@ -57,7 +57,7 @@ interface Routine { * var v = dsumkbn2.ndarray( x.length, x, 1, 0 ); * // returns 1.0 */ - ndarray( N: number, x: Float64Array, stride: number, offset: number ): number; + ndarray( N: number, x: Float64Array, strideX: number, offsetX: number ): number; } /** @@ -65,7 +65,7 @@ interface Routine { * * @param N - number of indexed elements * @param x - input array -* @param stride - stride length +* @param strideX - stride length * @returns sum * * @example diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/c/example.c b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/c/example.c index 3fceb0339216..216365c5ba3e 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/c/example.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/c/example.c @@ -17,7 +17,6 @@ */ #include "stdlib/blas/ext/base/dsumkbn2.h" -#include #include int main( void ) { @@ -25,13 +24,13 @@ int main( void ) { const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 }; // Specify the number of elements: - const int64_t N = 4; + const int N = 4; // Specify the stride length: - const int64_t stride = 2; + const int strideX = 2; // Compute the sum: - double v = stdlib_strided_dsumkbn2( N, x, stride ); + double v = stdlib_strided_dsumkbn2( N, x, strideX ); // Print the result: printf( "sum: %lf\n", v ); diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/index.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/index.js index c3b802e07f38..48def1b1b42b 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/index.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/examples/index.js @@ -18,11 +18,12 @@ 'use strict'; -var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); var dsumkbn2 = require( './../lib' ); -var x = filledarrayBy( 10, 'float64', discreteUniform( -100, 100 ) ); +var x = discreteUniform( 10, -100, 100, { + 'dtype': 'float64' +}); console.log( x ); var v = dsumkbn2( x.length, x, 1 ); diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/include/stdlib/blas/ext/base/dsumkbn2.h b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/include/stdlib/blas/ext/base/dsumkbn2.h index 510ae882cdfd..e3dbd459c213 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/include/stdlib/blas/ext/base/dsumkbn2.h +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/include/stdlib/blas/ext/base/dsumkbn2.h @@ -19,7 +19,7 @@ #ifndef STDLIB_BLAS_EXT_BASE_DSUMKBN2_H #define STDLIB_BLAS_EXT_BASE_DSUMKBN2_H -#include +#include "stdlib/blas/base/shared.h" /* * If C++, prevent name mangling so that the compiler emits a binary file having undecorated names, thus mirroring the behavior of a C compiler. @@ -31,7 +31,12 @@ extern "C" { /** * Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. */ -double stdlib_strided_dsumkbn2( const int64_t N, const double *X, const int64_t stride ); +double API_SUFFIX(stdlib_strided_dsumkbn2)( const CBLAS_INT N, const double *X, const CBLAS_INT strideX ); + +/** +* Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm and alternative indexing semantics. +*/ +double API_SUFFIX(stdlib_strided_dsumkbn2_ndarray)( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); #ifdef __cplusplus } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.js index af09b995ffa2..ab046471f7da 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.js @@ -20,7 +20,8 @@ // MODULES // -var abs = require( '@stdlib/math/base/special/abs' ); +var stride2offset = require( '@stdlib/strided/base/stride2offset' ); +var ndarray = require( './ndarray.js' ); // MAIN // @@ -38,63 +39,19 @@ var abs = require( '@stdlib/math/base/special/abs' ); * * @param {PositiveInteger} N - number of indexed elements * @param {Float64Array} x - input array -* @param {integer} stride - stride length +* @param {integer} strideX - stride length * @returns {number} sum * * @example * var Float64Array = require( '@stdlib/array/float64' ); * * var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -* var N = x.length; * -* var v = dsumkbn2( N, x, 1 ); +* var v = dsumkbn2( x.length, x, 1 ); * // returns 1.0 */ -function dsumkbn2( N, x, stride ) { - var sum; - var ccs; - var ix; - var cs; - var cc; - var v; - var t; - var c; - var i; - - if ( N <= 0 ) { - return 0.0; - } - if ( N === 1 || stride === 0 ) { - return x[ 0 ]; - } - if ( stride < 0 ) { - ix = (1-N) * stride; - } else { - ix = 0; - } - sum = 0.0; - ccs = 0.0; // second order correction term for lost low order bits - cs = 0.0; // first order correction term for lost low order bits - for ( i = 0; i < N; i++ ) { - v = x[ ix ]; - t = sum + v; - if ( abs( sum ) >= abs( v ) ) { - c = (sum-t) + v; - } else { - c = (v-t) + sum; - } - sum = t; - t = cs + c; - if ( abs( cs ) >= abs( c ) ) { - cc = (cs-t) + c; - } else { - cc = (c-t) + cs; - } - cs = t; - ccs += cc; - ix += stride; - } - return sum + cs + ccs; +function dsumkbn2( N, x, strideX ) { + return ndarray( N, x, strideX, stride2offset( N, strideX ) ); } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.native.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.native.js index eb9fbb3338bb..edc4cb98de18 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/dsumkbn2.native.js @@ -30,20 +30,19 @@ var addon = require( './../src/addon.node' ); * * @param {PositiveInteger} N - number of indexed elements * @param {Float64Array} x - input array -* @param {integer} stride - stride length +* @param {integer} strideX - stride length * @returns {number} sum * * @example * var Float64Array = require( '@stdlib/array/float64' ); * * var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -* var N = x.length; * -* var v = dsumkbn2( N, x, 1 ); +* var v = dsumkbn2( x.length, x, 1 ); * // returns 1.0 */ -function dsumkbn2( N, x, stride ) { - return addon( N, x, stride ); +function dsumkbn2( N, x, strideX ) { + return addon( N, x, strideX ); } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/index.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/index.js index 52d959f2b369..f224b12dde83 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/index.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/index.js @@ -28,20 +28,17 @@ * var dsumkbn2 = require( '@stdlib/blas/ext/base/dsumkbn2' ); * * var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -* var N = x.length; * -* var v = dsumkbn2( N, x, 1 ); +* var v = dsumkbn2( x.length, x, 1 ); * // returns 1.0 * * @example * var Float64Array = require( '@stdlib/array/float64' ); -* var floor = require( '@stdlib/math/base/special/floor' ); * var dsumkbn2 = require( '@stdlib/blas/ext/base/dsumkbn2' ); * * var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); -* var N = 3;; * -* var v = dsumkbn2.ndarray( N, x, 2, 1 ); +* var v = dsumkbn2.ndarray( 4, x, 2, 1 ); * // returns 5.0 */ diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.js index fb283fd02921..64e5d6682dbe 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.js @@ -38,21 +38,19 @@ var abs = require( '@stdlib/math/base/special/abs' ); * * @param {PositiveInteger} N - number of indexed elements * @param {Float64Array} x - input array -* @param {integer} stride - stride length -* @param {NonNegativeInteger} offset - starting index +* @param {integer} strideX - stride length +* @param {NonNegativeInteger} offsetX - starting index * @returns {number} sum * * @example * var Float64Array = require( '@stdlib/array/float64' ); -* var floor = require( '@stdlib/math/base/special/floor' ); * * var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); -* var N = 4; * -* var v = dsumkbn2( N, x, 2, 1 ); +* var v = dsumkbn2( 4, x, 2, 1 ); * // returns 5.0 */ -function dsumkbn2( N, x, stride, offset ) { +function dsumkbn2( N, x, strideX, offsetX ) { var sum; var ccs; var ix; @@ -66,10 +64,10 @@ function dsumkbn2( N, x, stride, offset ) { if ( N <= 0 ) { return 0.0; } - if ( N === 1 || stride === 0 ) { - return x[ offset ]; + ix = offsetX; + if ( strideX === 0 ) { + return N * x[ ix ]; } - ix = offset; sum = 0.0; ccs = 0.0; // second order correction term for lost low order bits cs = 0.0; // first order correction term for lost low order bits @@ -90,7 +88,7 @@ function dsumkbn2( N, x, stride, offset ) { } cs = t; ccs += cc; - ix += stride; + ix += strideX; } return sum + cs + ccs; } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.native.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.native.js index 6fdd350530d2..e254d48df707 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/lib/ndarray.native.js @@ -20,9 +20,7 @@ // MODULES // -var minViewBufferIndex = require( '@stdlib/strided/base/min-view-buffer-index' ); -var offsetView = require( '@stdlib/strided/base/offset-view' ); -var addon = require( './dsumkbn2.native.js' ); +var addon = require( './../src/addon.node' ); // MAIN // @@ -32,26 +30,20 @@ var addon = require( './dsumkbn2.native.js' ); * * @param {PositiveInteger} N - number of indexed elements * @param {Float64Array} x - input array -* @param {integer} stride - stride length -* @param {NonNegativeInteger} offset - starting index +* @param {integer} strideX - stride length +* @param {NonNegativeInteger} offsetX - starting index * @returns {number} sum * * @example * var Float64Array = require( '@stdlib/array/float64' ); -* var floor = require( '@stdlib/math/base/special/floor' ); * * var x = new Float64Array( [ 2.0, 1.0, 2.0, -2.0, -2.0, 2.0, 3.0, 4.0 ] ); -* var N = 4; * -* var v = dsumkbn2( N, x, 2, 1 ); +* var v = dsumkbn2( 4, x, 2, 1 ); * // returns 5.0 */ -function dsumkbn2( N, x, stride, offset ) { - var view; - offset = minViewBufferIndex( N, stride, offset ); - view = offsetView( x, offset ); - - return addon( N, view, stride ); +function dsumkbn2( N, x, strideX, offsetX ) { + return addon.ndarray( N, x, strideX, offsetX ); } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/manifest.json b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/manifest.json index bcafb815b9e0..95e0331dd32d 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/manifest.json +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/manifest.json @@ -28,7 +28,7 @@ { "task": "build", "src": [ - "./src/dsumkbn2.c" + "./src/main.c" ], "include": [ "./include" @@ -40,13 +40,16 @@ "@stdlib/napi/argv", "@stdlib/napi/argv-int64", "@stdlib/napi/argv-strided-float64array", - "@stdlib/math/base/special/abs" + "@stdlib/strided/base/stride2offset", + "@stdlib/blas/base/shared", + "@stdlib/math/base/special/abs", + "@stdlib/napi/create-double" ] }, { "task": "benchmark", "src": [ - "./src/dsumkbn2.c" + "./src/main.c" ], "include": [ "./include" @@ -54,13 +57,15 @@ "libraries": [], "libpath": [], "dependencies": [ + "@stdlib/strided/base/stride2offset", + "@stdlib/blas/base/shared", "@stdlib/math/base/special/abs" ] }, { "task": "examples", "src": [ - "./src/dsumkbn2.c" + "./src/main.c" ], "include": [ "./include" @@ -68,6 +73,8 @@ "libraries": [], "libpath": [], "dependencies": [ + "@stdlib/strided/base/stride2offset", + "@stdlib/blas/base/shared", "@stdlib/math/base/special/abs" ] } diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/addon.c b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/addon.c index 322422386ad3..b896fa028e0d 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/addon.c +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/addon.c @@ -17,12 +17,13 @@ */ #include "stdlib/blas/ext/base/dsumkbn2.h" +#include "stdlib/blas/base/shared.h" #include "stdlib/napi/export.h" #include "stdlib/napi/argv.h" #include "stdlib/napi/argv_int64.h" #include "stdlib/napi/argv_strided_float64array.h" +#include "stdlib/napi/create_double.h" #include -#include /** * Receives JavaScript callback invocation data. @@ -36,11 +37,25 @@ static napi_value addon( napi_env env, napi_callback_info info ) { STDLIB_NAPI_ARGV_INT64( env, N, argv, 0 ); STDLIB_NAPI_ARGV_INT64( env, strideX, argv, 2 ); STDLIB_NAPI_ARGV_STRIDED_FLOAT64ARRAY( env, X, N, strideX, argv, 1 ); - - napi_value v; - napi_create_double( env, stdlib_strided_dsumkbn2( N, X, strideX ), &v ); + STDLIB_NAPI_CREATE_DOUBLE( env, API_SUFFIX(stdlib_strided_dsumkbn2)( N, X, strideX ), v ); + return v; +} +/** +* Receives JavaScript callback invocation data. +* +* @param env environment under which the function is invoked +* @param info callback data +* @return Node-API value +*/ +static napi_value addon_method( napi_env env, napi_callback_info info ) { + STDLIB_NAPI_ARGV( env, info, argv, argc, 4 ); + STDLIB_NAPI_ARGV_INT64( env, N, argv, 0 ); + STDLIB_NAPI_ARGV_INT64( env, strideX, argv, 2 ); + STDLIB_NAPI_ARGV_INT64( env, offsetX, argv, 3 ); + STDLIB_NAPI_ARGV_STRIDED_FLOAT64ARRAY( env, X, N, strideX, argv, 1 ); + STDLIB_NAPI_CREATE_DOUBLE( env, API_SUFFIX(stdlib_strided_dsumkbn2_ndarray)( N, X, strideX, offsetX ), v ); return v; } -STDLIB_NAPI_MODULE_EXPORT_FCN( addon ); +STDLIB_NAPI_MODULE_EXPORT_FCN_WITH_METHOD( addon, "ndarray", addon_method ) diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/dsumkbn2.c b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/dsumkbn2.c deleted file mode 100644 index 49bc11fdff51..000000000000 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/dsumkbn2.c +++ /dev/null @@ -1,84 +0,0 @@ -/** -* @license Apache-2.0 -* -* Copyright (c) 2020 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. -*/ - -#include "stdlib/blas/ext/base/dsumkbn2.h" -#include "stdlib/math/base/special/abs.h" -#include - -/** -* Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. -* -* ## Method -* -* - This implementation uses a second-order iterative Kahan–Babuška algorithm, as described by Klein (2005). -* -* ## References -* -* - Klein, Andreas. 2005. "A Generalized Kahan-Babuška-Summation-Algorithm." _Computing_ 76 (3): 279–93. doi:[10.1007/s00607-005-0139-x](https://doi.org/10.1007/s00607-005-0139-x). -* -* @param N number of indexed elements -* @param X input array -* @param stride stride length -* @return output value -*/ -double stdlib_strided_dsumkbn2( const int64_t N, const double *X, const int64_t stride ) { - double sum; - double ccs; - int64_t ix; - int64_t i; - double cs; - double cc; - double v; - double t; - double c; - - if ( N <= 0 ) { - return 0.0; - } - if ( N == 1 || stride == 0 ) { - return X[ 0 ]; - } - if ( stride < 0 ) { - ix = (1-N) * stride; - } else { - ix = 0; - } - sum = 0.0; - ccs = 0.0; // second order correction term for lost lower order bits - cs = 0.0; // first order correction term for lost low order bits - for ( i = 0; i < N; i++ ) { - v = X[ ix ]; - t = sum + v; - if ( stdlib_base_abs( sum ) >= stdlib_base_abs( v ) ) { - c = (sum-t) + v; - } else { - c = (v-t) + sum; - } - sum = t; - t = cs + c; - if ( stdlib_base_abs( cs ) >= stdlib_base_abs( c ) ) { - cc = (cs-t) + c; - } else { - cc = (c-t) + cs; - } - cs = t; - ccs += cc; - ix += stride; - } - return sum + cs + ccs; -} diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/main.c b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/main.c new file mode 100644 index 000000000000..43ea376f1f05 --- /dev/null +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/src/main.c @@ -0,0 +1,103 @@ +/** +* @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. +*/ + +#include "stdlib/blas/ext/base/dsumkbn2.h" +#include "stdlib/math/base/special/abs.h" +#include "stdlib/blas/base/shared.h" +#include "stdlib/strided/base/stride2offset.h" + +/** +* Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm. +* +* ## Method +* +* - This implementation uses a second-order iterative Kahan–Babuška algorithm, as described by Klein (2005). +* +* ## References +* +* - Klein, Andreas. 2005. "A Generalized Kahan-Babuška-Summation-Algorithm." _Computing_ 76 (3): 279–93. doi:[10.1007/s00607-005-0139-x](https://doi.org/10.1007/s00607-005-0139-x). +* +* @param N number of indexed elements +* @param X input array +* @param strideX stride length +* @return output value +*/ +double API_SUFFIX(stdlib_strided_dsumkbn2)( const CBLAS_INT N, const double *X, const CBLAS_INT strideX ) { + CBLAS_INT ox = stdlib_strided_stride2offset( N, strideX ); + return API_SUFFIX( stdlib_strided_dsumkbn2_ndarray )( N, X, strideX, ox ); +} + +/** +* Computes the sum of double-precision floating-point strided array elements using a second-order iterative Kahan–Babuška algorithm and alternative indexing semantics. +* +* ## Method +* +* - This implementation uses a second-order iterative Kahan–Babuška algorithm, as described by Klein (2005). +* +* ## References +* +* - Klein, Andreas. 2005. "A Generalized Kahan-Babuška-Summation-Algorithm." _Computing_ 76 (3): 279–93. doi:[10.1007/s00607-005-0139-x](https://doi.org/10.1007/s00607-005-0139-x). +* +* @param N number of indexed elements +* @param X input array +* @param strideX stride length +* @param offsetX starting index +* @return output value +*/ +double API_SUFFIX(stdlib_strided_dsumkbn2_ndarray)( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ) { + CBLAS_INT ix; + CBLAS_INT i; + double sum; + double ccs; + double cs; + double cc; + double v; + double t; + double c; + + if ( N <= 0 ) { + return 0.0; + } + ix = offsetX; + if ( strideX == 0 ) { + return N * X[ ix ]; + } + sum = 0.0; + ccs = 0.0; // second order correction term for lost lower order bits + cs = 0.0; // first order correction term for lost low order bits + for ( i = 0; i < N; i++ ) { + v = X[ ix ]; + t = sum + v; + if ( stdlib_base_abs( sum ) >= stdlib_base_abs( v ) ) { + c = (sum-t) + v; + } else { + c = (v-t) + sum; + } + sum = t; + t = cs + c; + if ( stdlib_base_abs( cs ) >= stdlib_base_abs( c ) ) { + cc = (cs-t) + c; + } else { + cc = (c-t) + cs; + } + cs = t; + ccs += cc; + ix += strideX; + } + return sum + cs + ccs; +} diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.js index 0e74cf92c7cb..87c207198eea 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.js @@ -139,14 +139,14 @@ tape( 'the function supports a negative `stride` parameter', function test( t ) t.end(); }); -tape( 'if provided a `stride` parameter equal to `0`, the function returns the first element', function test( t ) { +tape( 'if provided a `stride` parameter equal to `0`, the function returns the sum of the first element repeated N times', function test( t ) { var x; var v; x = new Float64Array( [ 1.0, -2.0, -4.0, 5.0, 3.0 ] ); v = dsumkbn2( x.length, x, 0 ); - t.strictEqual( v, 1.0, 'returns expected value' ); + t.strictEqual( v, 5.0, 'returns expected value' ); t.end(); }); diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.native.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.native.js index 09a7a5b243f5..831a125f8370 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.dsumkbn2.native.js @@ -230,14 +230,14 @@ tape( 'the function supports a negative `stride` parameter', opts, function test t.end(); }); -tape( 'if provided a `stride` parameter equal to `0`, the function returns the first element', opts, function test( t ) { +tape( 'if provided a `stride` parameter equal to `0`, the function returns the sum of the first element repeated N times', opts, function test( t ) { var x; var v; x = new Float64Array( [ 1.0, -2.0, -4.0, 5.0, 3.0 ] ); v = dsumkbn2( x.length, x, 0 ); - t.strictEqual( v, 1.0, 'returns expected value' ); + t.strictEqual( v, 5.0, 'returns expected value' ); t.end(); }); diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.js index 6eaad80ee38d..e5b1b366b09a 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.js @@ -139,14 +139,14 @@ tape( 'the function supports a negative `stride` parameter', function test( t ) t.end(); }); -tape( 'if provided a `stride` parameter equal to `0`, the function returns the first indexed element', function test( t ) { +tape( 'if provided a `stride` parameter equal to `0`, the function returns the sum of the first element repeated N times', function test( t ) { var x; var v; x = new Float64Array( [ 1.0, -2.0, -4.0, 5.0, 3.0 ] ); v = dsumkbn2( x.length, x, 0, 0 ); - t.strictEqual( v, 1.0, 'returns expected value' ); + t.strictEqual( v, 5.0, 'returns expected value' ); t.end(); }); diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.native.js b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.native.js index 668f399f2ab6..2fee9488664e 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.native.js +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumkbn2/test/test.ndarray.native.js @@ -148,14 +148,14 @@ tape( 'the function supports a negative `stride` parameter', opts, function test t.end(); }); -tape( 'if provided a `stride` parameter equal to `0`, the function returns the first indexed element', opts, function test( t ) { +tape( 'if provided a `stride` parameter equal to `0`, the function returns the sum of the first element repeated N times', opts, function test( t ) { var x; var v; x = new Float64Array( [ 1.0, -2.0, -4.0, 5.0, 3.0 ] ); v = dsumkbn2( x.length, x, 0, 0 ); - t.strictEqual( v, 1.0, 'returns expected value' ); + t.strictEqual( v, 5.0, 'returns expected value' ); t.end(); }); diff --git a/lib/node_modules/@stdlib/blas/ext/base/dsumors/README.md b/lib/node_modules/@stdlib/blas/ext/base/dsumors/README.md index a68ee7615de1..24d284967a28 100644 --- a/lib/node_modules/@stdlib/blas/ext/base/dsumors/README.md +++ b/lib/node_modules/@stdlib/blas/ext/base/dsumors/README.md @@ -36,7 +36,7 @@ limitations under the License. var dsumors = require( '@stdlib/blas/ext/base/dsumors' ); ``` -#### dsumors( N, x, stride ) +#### dsumors( N, x, strideX ) Computes the sum of double-precision floating-point strided array elements using ordinary recursive summation. @@ -44,9 +44,8 @@ Computes the sum of double-precision floating-point strided array elements using var Float64Array = require( '@stdlib/array/float64' ); var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -var N = x.length; -var v = dsumors( N, x, 1 ); +var v = dsumors( x.length, x, 1 ); // returns 1.0 ``` @@ -54,9 +53,9 @@ The function has the following parameters: - **N**: number of indexed elements. - **x**: input [`Float64Array`][@stdlib/array/float64]. -- **stride**: index increment for `x`. +- **strideX**: stride length for `x`. -The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element in `x`, +The `N` and stride parameters determine which elements in the strided array are accessed at runtime. For example, to compute the sum of every other element: ```javascript var Float64Array = require( '@stdlib/array/float64' ); @@ -81,7 +80,7 @@ var v = dsumors( 4, x1, 2 ); // returns 5.0 ``` -#### dsumors.ndarray( N, x, stride, offset ) +#### dsumors.ndarray( N, x, strideX, offsetX ) Computes the sum of double-precision floating-point strided array elements using ordinary recursive summation and alternative indexing semantics. @@ -89,17 +88,16 @@ Computes the sum of double-precision floating-point strided array elements using var Float64Array = require( '@stdlib/array/float64' ); var x = new Float64Array( [ 1.0, -2.0, 2.0 ] ); -var N = x.length; -var v = dsumors.ndarray( N, x, 1, 0 ); +var v = dsumors.ndarray( x.length, x, 1, 0 ); // returns 1.0 ``` The function has the following additional parameters: -- **offset**: starting index for `x`. +- **offsetX**: starting index for `x`. -While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offset` parameter supports indexing semantics based on a starting index. For example, to calculate the sum of every other value in `x` starting from the second value +While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying buffer, the offset parameter supports indexing semantics based on a starting index. For example, to calculate the sum of every other element starting from the second element: ```javascript var Float64Array = require( '@stdlib/array/float64' ); @@ -132,11 +130,12 @@ var v = dsumors.ndarray( 4, x, 2, 1 ); ```javascript -var discreteUniform = require( '@stdlib/random/base/discrete-uniform' ).factory; -var filledarrayBy = require( '@stdlib/array/filled-by' ); +var discreteUniform = require( '@stdlib/random/array/discrete-uniform' ); var dsumors = require( '@stdlib/blas/ext/base/dsumors' ); -var x = filledarrayBy( 10, 'float64', discreteUniform( 0, 100 ) ); +var x = discreteUniform( 10, -100, 100, { + 'dtype': 'float64' +}); console.log( x ); var v = dsumors( x.length, x, 1 ); @@ -147,6 +146,123 @@ console.log( v ); + + +* * * + +
+ +## C APIs + + + +
+ +
+ + + + + +
+ +### Usage + +```c +#include "stdlib/blas/ext/base/dsumors.h" +``` + +#### stdlib_strided_dsumors( N, \*X, strideX ) + +Computes the sum of double-precision floating-point strided array elements using ordinary recursive summation. + +```c +const double x[] = { 1.0, 2.0, 3.0, 4.0 }; + +double v = stdlib_strided_dsumors( 4, x, 1 ); +// returns 10.0 +``` + +The function accepts the following arguments: + +- **N**: `[in] CBLAS_INT` number of indexed elements. +- **X**: `[in] double*` input array. +- **strideX**: `[in] CBLAS_INT` stride length for `X`. + +```c +double stdlib_strided_dsumors( const CBLAS_INT N, const double *X, const CBLAS_INT strideX ); +``` + +#### stdlib_strided_dsumors_ndarray( N, \*X, strideX, offsetX ) + +Computes the sum of double-precision floating-point strided array elements using ordinary recursive summation and alternative indexing semantics. + +```c +const double x[] = { 1.0, 2.0, 3.0, 4.0 }; + +double v = stdlib_strided_dsumors_ndarray( 4, x, 1, 0 ); +// returns 10.0 +``` + +The function accepts the following arguments: + +- **N**: `[in] CBLAS_INT` number of indexed elements. +- **X**: `[in] double*` input array. +- **strideX**: `[in] CBLAS_INT` stride length for `X`. +- **offsetX**: `[in] CBLAS_INT` starting index for `X`. + +```c +double stdlib_strided_dsumors_ndarray( const CBLAS_INT N, const double *X, const CBLAS_INT strideX, const CBLAS_INT offsetX ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +### Examples + +```c +#include "stdlib/blas/ext/base/dsumors.h" +#include + +int main( void ) { + // Create a strided array: + const double x[] = { 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0 }; + + // Specify the number of elements: + const int N = 4; + + // Specify the stride length: + const int strideX = 2; + + // Compute the sum: + double v = stdlib_strided_dsumors( N, x, strideX ); + + // Print the result: + printf( "sum: %lf\n", v ); +} +``` + +
+ + + +
+ + +