feat: add number/float64/base/assert/is-almost-equal-value

---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
  - task: lint_filenames
    status: passed
  - task: lint_editorconfig
    status: passed
  - task: lint_markdown
    status: passed
  - task: lint_package_json
    status: passed
  - task: lint_repl_help
    status: passed
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: passed
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: passed
  - task: lint_python
    status: na
  - task: lint_r
    status: na
  - task: lint_c_src
    status: na
  - task: lint_c_examples
    status: na
  - task: lint_c_benchmarks
    status: na
  - task: lint_c_tests_fixtures
    status: na
  - task: lint_shell
    status: na
  - task: lint_typescript_declarations
    status: passed
  - task: lint_typescript_tests
    status: passed
  - task: lint_license_headers
    status: passed
---

Author: anandkaranubc

lib/node_modules/@stdlib/number/float64/base/assert/is-almost-equal-value/README.md

@@ -2,7 +2,7 @@
 
 @license Apache-2.0
 
-Copyright (c) 2024 The Stdlib Authors.
+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.
@@ -18,48 +18,49 @@ limitations under the License.
 
 -->
 
-# isSameValue
+# isAlmostEqualValue
 
-> Test if two double-precision floating-point numbers are the same value.
+> Test if two double-precision floating-point numbers are approximately equal within a specified number of ULPs (units in the last place).
 
 <section class="usage">
 
 ## Usage
 
 ```javascript
-var isSameValue = require( '@stdlib/number/float64/base/assert/is-same-value' );
+var isAlmostEqualValue = require( '@stdlib/number/float64/base/assert/is-almost-equal-value' );
 ```
 
-#### isSameValue( a, b )
+#### isAlmostEqualValue( a, b )
 
-Tests if two double-precision floating-point numbers `a` and `b` are the same value.
+Test if two double-precision floating-point numbers are approximately equal within a specified number of ULPs (units in the last place).
 
 ```javascript
-var bool = isSameValue( 3.14, 3.14 );
+var EPS = require( '@stdlib/constants/float64/eps' );
+
+var bool = isAlmostEqualValue( 1.0, 1.0+EPS, 1 );
 // returns true
 
-bool = isSameValue( 5.0, 3.0 );
+bool = isAlmostEqualValue( 1.0, 1.0+EPS, 0 );
 // returns false
 ```
 
-In contrast to the strict equality operator `===`, the function distinguishes between `+0` and `-0` and treats `NaNs` as the same value.
-
-<!-- eslint-disable no-compare-neg-zero, use-isnan -->
+The function returns `false` if either input value is `NaN`.
 
 ```javascript
-var bool = ( 0.0 === -0.0 );
-// returns true
-
-bool = isSameValue( 0.0, -0.0 );
+var bool = isAlmostEqualValue( NaN, 1.0, 1 );
 // returns false
 
-bool = isSameValue( -0.0, -0.0 );
-// returns true
+bool = isAlmostEqualValue( 1.0, NaN, 1 );
+// returns false
 
-bool = ( NaN === NaN );
+bool = isAlmostEqualValue( NaN, NaN, 1 );
 // returns false
+```
+
+The function does not distinguish between `-0` and `+0`, treating them as equal.
 
-bool = isSameValue( NaN, NaN );
+```javascript
+var bool = isAlmostEqualValue( 0.0, -0.0, 0 );
 // returns true
 ```
 
@@ -69,10 +70,6 @@ bool = isSameValue( NaN, NaN );
 
 <section class="notes">
 
-## Notes
-
--   The function implements the [SameValue Algorithm][ecma-262-same-value-algorithm] as specified in ECMAScript 5.
-
 </section>
 
 <!-- /.notes -->
@@ -84,128 +81,42 @@ bool = isSameValue( NaN, NaN );
 <!-- eslint no-undef: "error" -->
 
 ```javascript
-var isSameValue = require( '@stdlib/number/float64/base/assert/is-same-value' );
-
-var bool = isSameValue( 3.14, 3.14 );
-// returns true
-
-bool = isSameValue( 0.0, 0.0 );
-// returns true
-
-bool = isSameValue( -0.0, 0.0 );
-// returns false
-
-bool = isSameValue( NaN, NaN );
-// returns true
-```
-
-</section>
-
-<!-- /.examples -->
+var EPS = require( '@stdlib/constants/float64/eps' );
+var isAlmostEqualValue = require( '@stdlib/number/float64/base/assert/is-almost-equal-value' );
 
-<!-- C interface documentation. -->
+var bool = isAlmostEqualValue( 1.0, 1.0+EPS, 1 );
+console.log( bool );
+// => true
 
-* * *
+bool = isAlmostEqualValue( 1.0+EPS, 1.0, 1 );
+console.log( bool );
+// => true
 
-<section class="c">
+bool = isAlmostEqualValue( 1.0, 1.0+EPS+EPS, 1 );
+console.log( bool );
+// => false
 
-## C APIs
+bool = isAlmostEqualValue( 1.0, 1.0+EPS, 0 );
+console.log( bool );
+// => false
 
-<!-- Section to include introductory text. Make sure to keep an empty line after the intro `section` element and another before the `/section` close. -->
+bool = isAlmostEqualValue( -0.0, 0.0, 0 );
+console.log( bool );
+// => true
 
-<section class="intro">
+bool = isAlmostEqualValue( 1.0, NaN, 1 );
+console.log( bool );
+// => false
 
-</section>
-
-<!-- /.intro -->
-
-<!-- C usage documentation. -->
-
-<section class="usage">
-
-### Usage
-
-```c
-#include "stdlib/number/float64/base/assert/is_same_value.h"
-```
-
-#### stdlib_base_float64_is_same_value( a, b )
-
-Tests if two double-precision floating-point numbers `a` and `b` are the same value.
-
-```c
-#include <stdbool.h>
-
-bool v = stdlib_base_float64_is_same_value( 3.14, 3.14 );
-// returns true
-
-v = stdlib_base_float64_is_same_value( 0.0, -0.0 );
-// returns false
-```
-
-The function accepts the following arguments:
-
--   **a**: `[in] double` first input value.
--   **b**: `[in] double` second input value.
-
-```c
-bool stdlib_base_float64_is_same_value( const double a, const double b );
-```
-
-</section>
-
-<!-- /.usage -->
-
-<!-- C API usage notes. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
-
-<section class="notes">
-
-</section>
-
-<!-- /.notes -->
-
-<!-- C API usage examples. -->
-
-<section class="examples">
-
-### Examples
-
-```c
-#include "stdlib/number/float64/base/assert/is_same_value.h"
-#include <stdbool.h>
-#include <stdio.h>
-
-int main( void ) {
-    const double a[] = {
-        5.0,
-        -2.0,
-        0.0,
-        0.0/0.0
-    };
-    const double b[] = {
-        5.0,
-        2.0,
-        -0.0,
-        0.0/0.0
-    };
-
-    bool v;
-    int i;
-    for ( i = 0; i < 4; i++ ) {
-        v = stdlib_base_float64_is_same_value( a[ i ], b[ i ] );
-        printf( "Same value? %s\n", ( v ) ? "True" : "False" );
-    }
-}
+bool = isAlmostEqualValue( NaN, NaN, 1 );
+console.log( bool );
+// => false
 ```
 
 </section>
 
 <!-- /.examples -->
 
-</section>
-
-<!-- /.c -->
-
 <!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
 
 <section class="related">
@@ -218,8 +129,6 @@ int main( void ) {
 
 <section class="links">
 
-[ecma-262-same-value-algorithm]: http://ecma-international.org/ecma-262/5.1/#sec-9.12
-
 </section>
 
 <!-- /.links -->

lib/node_modules/@stdlib/number/float64/base/assert/is-almost-equal-value/benchmark/benchmark.js

@@ -1,7 +1,7 @@
 /**
 * @license Apache-2.0
 *
-* Copyright (c) 2024 The Stdlib Authors.
+* 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.
@@ -23,7 +23,7 @@
 var bench = require( '@stdlib/bench' );
 var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive;
 var pkg = require( './../package.json' ).name;
-var isSameValue = require( './../lib' );
+var isAlmostEqualValue = require( './../lib' );
 
 
 // MAIN //
@@ -46,7 +46,7 @@ bench( pkg, function benchmark( b ) {
 	b.tic();
 	for ( i = 0; i < b.iterations; i++ ) {
 		v = values[ i%values.length ];
-		bool = isSameValue( v, v );
+		bool = isAlmostEqualValue( v, v, 1 );
 		if ( typeof bool !== 'boolean' ) {
 			b.fail( 'should return a boolean' );
 		}

lib/node_modules/@stdlib/number/float64/base/assert/is-almost-equal-value/docs/repl.txt

@@ -1,9 +1,12 @@
 
-{{alias}}( a, b )
-    Tests if two double-precision floating-point numbers are the same value.
+{{alias}}( a, b, maxULP )
+    Tests if two double-precision floating-point numbers are approximately equal
+    within a specified number of ULPs (units in the last place).
 
-    The function differs from the `===` operator in that the function treats
-    `-0` and `+0` as distinct and `NaNs` as the same.
+    The function returns `false` if either input value is `NaN`.
+
+    The function does not distinguish between `-0` and `+0`, treating them as
+    equal.
 
     Parameters
     ----------
@@ -13,20 +16,29 @@
     b: number
         Second input value.
 
+    maxULP: number
+        Maximum allowed ULP difference.
+
     Returns
     -------
     bool: boolean
         Boolean indicating whether two double-precision floating-point numbers
-        are the same value.
+        are approximately equal within a specified number of ULPs.
 
     Examples
     --------
-    > var bool = {{alias}}( -0.0, -0.0 )
+    > var bool = {{alias}}( 1, 1+{{alias:@stdlib/constants/float64/eps}}, 1 )
+    true
+    > bool = {{alias}}( 1+{{alias:@stdlib/constants/float64/eps}}, 1, 1 )
     true
-    > bool = {{alias}}( -0.0, 0.0 )
+    > bool = {{alias}}( 1, 1+{{alias:@stdlib/constants/float64/eps}}*2, 1 )
     false
-    > bool = {{alias}}( NaN, NaN )
+    > bool = {{alias}}( 0.0, -0.0, 0 )
     true
+    > bool = {{alias}}( NaN, 1.0, 1 )
+    false
+    > bool = {{alias}}( NaN, NaN, 0 )
+    false
 
     See Also
     --------

lib/node_modules/@stdlib/number/float64/base/assert/is-almost-equal-value/docs/types/index.d.ts

@@ -1,7 +1,7 @@
 /*
 * @license Apache-2.0
 *
-* Copyright (c) 2024 The Stdlib Authors.
+* 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.
@@ -19,35 +19,45 @@
 // TypeScript Version: 4.1
 
 /**
-* Tests if two double-precision floating-point numbers are the same value.
+* Tests if two double-precision floating-point numbers are approximately equal within a specified number of ULPs (units in the last place).
 *
 * ## Notes
 *
-* -   The function differs from the `===` operator in that the function treats `-0` and `+0` as distinct and `NaNs` as the same.
+* -   The function returns `false` if either input value is `NaN`.
+* -   The function does not distinguish between `-0` and `+0`, treating them as equal.
 *
 * @param a - first input value
 * @param b - second input value
-* @returns boolean indicating whether two double-precision floating-point numbers are the same value
+* @param maxULP - maximum allowed ULP difference
+* @returns boolean indicating whether two double-precision floating-point numbers are approximately equal within a specified number of ULPs
 *
 * @example
-* var bool = isSameValue( 3.14, 3.14 );
+* var EPS = require( '@stdlib/constants/float64/eps' );
+*
+* var bool = isAlmostEqualValue( 1.0, 1.0+EPS, 1 );
 * // returns true
 *
-* @example
-* var bool = isSameValue( -0.0, -0.0 );
+* var bool = isAlmostEqualValue( 1.0+EPS, 1.0, 1 );
 * // returns true
 *
-* @example
-* var bool = isSameValue( -0.0, 0.0 );
+* bool = isAlmostEqualValue( 1.0, 1.0+EPS+EPS, 1 );
 * // returns false
 *
-* @example
-* var bool = isSameValue( NaN, NaN );
+* bool = isAlmostEqualValue( 1.0, 1.0+EPS, 0 );
+* // returns false
+*
+* bool = isAlmostEqualValue( 0.0, -0.0, 0 );
 * // returns true
+*
+* bool = isAlmostEqualValue( 1.0, NaN, 1 );
+* // returns false
+*
+* bool = isAlmostEqualValue( NaN, NaN, 1 );
+* // returns false
 */
-declare function isSameValue( a: number, b: number ): boolean;
+declare function isAlmostEqualValue( a: number, b: number, maxULP: number ): boolean;
 
 
 // EXPORTS //
 
-export = isSameValue;
+export = isAlmostEqualValue;