feat: add number/float16/base/ulp-difference

[Neerajpathak07]

Resolves none.

Description

What is the purpose of this pull request?

This pull request:

• Adds number/float16/base/ulp-difference

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• none

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

{{TODO: add disclosure if applicable}}

---

@stdlib-js/reviewers

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
number/float16/base/ulp-difference	$\color{green}161/161$ $\color{green}+0.00%$	$\color{green}9/9$ $\color{green}+0.00%$	$\color{green}2/2$ $\color{green}+0.00%$	$\color{green}161/161$ $\color{green}+0.00%$

The above coverage report was generated for the changes in this PR.

[kgryte]

Overall, this looks good. My main question is around monotone key conversion.

[Neerajpathak07]

Tested the two-complements negation logic with the following edge cases:-

d = ulpdiff( -1.1920928955078125e-7, -5.960464477539063e-8 );
console.log( d );
// => 1.0

d = ulpdiff( -5.960464477539063e-8, 5.960464477539063e-8 );
console.log( d );
// => 2.0

output log:-

[Running] node "c:\Users\HP\Stdlib\stdlib\lib\node_modules\@stdlib\number\float16\base\ulp-difference\test\edgeCase.js"
1
2

1. adjacent negative values should differ by exactly 1 ULP, and it's returning 1 correctly.
2. to confirm if sign boundary ordering is correct (same as SMALLEST_SUBNORMAL).

what I believe if the logic was broken it would have provided huge ulp diff.

[kgryte]

LGTM. I confirmed that ordering works correctly with the following script:

'use strict';

// MODULES //

var toWord = require( '@stdlib/number/float16/base/to-word' );
var fromWord = require( '@stdlib/number/float16/base/from-word' );
var UINT16_MAX = require( '@stdlib/constants/uint16/max' );
var SIGN_MASK = require( '@stdlib/constants/float16/sign-mask' );
var isNegativeZero = require( '@stdlib/math/base/assert/is-negative-zero' );


// FUNCTIONS //

/**
* Converts an unsigned 16-bit integer corresponding to the IEEE 754 binary representation of a half-precision floating-point number to a lexicographically ordered integer.
*
* @private
* @param {unsigned16} word - unsigned 16-bit integer
* @returns {integer} lexicographically ordered integer
*/
function monotoneKey( word ) {
	if ( word & SIGN_MASK ) { // x < 0
		return ( ( ~word + 1 ) &UINT16_MAX ); // two's-complement negation
	}
	// x >= 0
	return ( word | SIGN_MASK ) >>> 0; // push +0 to just above -0
}

/**
* Comparator function.
*
* @private
* @param {number} a - first number
* @param {number} b - second number
* @returns {integer} value indicating sort order
*/
function compare( a, b ) {
	if ( a !== a ) {
		return 1;
	}
	if ( b !== b ) {
		return -1;
	}
	if ( a < b ) {
		return -1;
	}
	if ( a > b ) {
		return 1;
	}
	if ( isNegativeZero( a ) ) {
		return -1;
	}
	return 0;
}


// MAIN //

/**
* Main execution sequence.
*
* @private
*/
function main() {
	var values;
	var i;

	values = [];
	for ( i = 0; i <= UINT16_MAX; i++ ) {
		values.push( fromWord( i ) );
	}
	values.sort( compare );

	for ( i = 0; i < values.length; i++ ) {
		console.log( '%d => %d', monotoneKey( toWord( values[ i ] ) ), values[ i ] );
	}
}

main();

If you run that and pipe to results.txt and inspect the results, you can confirm that lexicographic ordering works as expected.