feat: add Int64 support

lib/node_modules/@stdlib/_tools/doctest/compare-values/lib/main.js

@@ -16,7 +16,7 @@
 * limitations under the License.
 */
 
-/* eslint-disable stdlib/no-empty-lines-between-requires */
+/* eslint-disable stdlib/no-empty-lines-between-requires, max-lines */
 
 'use strict';
 
@@ -78,6 +78,7 @@
 var isUint8ClampedArray = require( '@stdlib/assert/is-uint8clampedarray' );
 var isUint16Array = require( '@stdlib/assert/is-uint16array' );
 var isUint32Array = require( '@stdlib/assert/is-uint32array' );
+var isInt64 = require( '@stdlib/assert/is-int64' );
 var isUint64 = require( '@stdlib/assert/is-uint64' );
 var isUndefined = require( '@stdlib/assert/is-undefined' );
 var isURIError = require( '@stdlib/assert/is-uri-error' );
@@ -285,6 +286,8 @@
 		return isInt16Array( actual );
 	case '<Int32Array>':
 		return isInt32Array( actual );
+	case '<Int64>':
+		return isInt64( actual );
 	case '<MultiSlice>':
 		return isMultiSlice( actual );
 	case '<ndarray>':
@@ -332,7 +335,7 @@
 	default:
 		// 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;
 	}
 }
@@ -392,14 +395,14 @@
 }
 
 /**
-* Checks whether an unsigned 64-bit integer matches the expected return annotation.
+* Checks whether a 64-bit (signed or unsigned) integer matches the expected return annotation.
 *
 * @private
 * @param {*} actual - actual return value
 * @param {string} expected - return value annotation
 * @returns {(string|null)} error message or null
 */
-function checkUint64( actual, expected ) {
+function checkInt64( actual, expected ) {
 	var entries;
 	var match;
 	var type;
@@ -417,7 +420,7 @@
 		}
 		return null;
 	}
-	return 'Unsigned 64-bit integers should be documented using instance annotation';
+	return '64-bit integers should be documented using instance annotation';
 }
 
 /**
@@ -667,9 +670,9 @@
 	if ( isComplex64( actual ) || isComplex128( actual ) ) {
 		return checkComplex( actual, expected );
 	}
-	// Case: compareValues( new Uint64( 1234 ), '<Uint64>[ 1234n ]' )
-	if ( isUint64( actual ) ) {
-		return checkUint64( actual, expected );
+	// Case: compareValues( new Int64( 1234 ), '<Int64>[ 1234n ]' )
+	if ( isInt64( actual ) || isUint64( actual ) ) {
+		return checkInt64( actual, expected );
 	}
 	// Case: compareValues( array( [ 1.0, 2.0 ] ), '<ndarray>[ 1.0, 2.0 ]' )
 	if ( isndarrayLike( actual ) ) {

lib/node_modules/@stdlib/_tools/doctest/compare-values/test/test.js

@@ -25,6 +25,7 @@
 var hasBigInt64ArraySupport = require( '@stdlib/assert/has-bigint64array-support' );
 var hasBigUint64ArraySupport = require( '@stdlib/assert/has-biguint64array-support' );
 var Number = require( '@stdlib/number/ctor' );
+var Int64 = require( '@stdlib/number/int64/ctor' );
 var Uint64 = require( '@stdlib/number/uint64/ctor' );
 var Boolean = require( '@stdlib/boolean/ctor' );
 var BigInt = require( '@stdlib/bigint/ctor' );
@@ -164,7 +165,7 @@
 	t.end();
 });
 
-tape( 'the function compares an array and a corresponding return annotation', function test( t ) {
+tape( 'the function compares an array and a corresponding return annotation', function test( t ) { // eslint-disable-line max-statements
 	var expected;
 	var actual;
 	var msg;
@@ -487,11 +488,56 @@
 	t.end();
 });
 
-tape( 'the function compares an unsigned 64-bit integer and a corresponding return annotation', function test( t ) {
+tape( 'the function compares a 64-bit (signed or unsigned) integer and a corresponding return annotation', function test( t ) {
 	var expected;
 	var actual;
 	var msg;
 
+	// Signed:
+	actual = new Int64( 1234 );
+	expected = '<Int64>';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns expected value' );
+
+	actual = new Int64( 1234 );
+	expected = '<Int64>[ 1234n ]';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns expected value' );
+
+	actual = new Int64( 1234 );
+	expected = '<Int64>[ 1234 ]';
+	msg = 'Expected entries [1234], but observed [1234n]';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Int64( 1234 );
+	expected = '<Int64>[ 5678n ]';
+	msg = 'Expected entries [5678n], but observed [1234n]';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Int64( 1234 );
+	expected = '<Uint64>';
+	msg = 'Expected a <Uint64>, but received: `1234`'; // FIXME: `1234` doesn't seem right in this context, we should mention received `Int64`
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Int64( 1234 );
+	expected = '<Uint64>[ 1234n ]';
+	msg = 'Expected instance type <Uint64>, but observed <Int64>';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Int64( 1234 );
+	expected = '<Something>';
+	msg = null; // FIXME: this should not return null, it's a false negative
+	t.strictEqual( compareValues( actual, expected ), null, 'returns expected message' );
+
+	actual = new Int64( 1234 );
+	expected = '<Something>[ 1234n ]';
+	msg = 'Expected instance type <Something>, but observed <Int64>';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Int64( 1234 );
+	expected = '<Complex128>[ 2.0, 3.0 ]';
+	msg = 'Expected instance type <Complex128>, but observed <Int64>';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	// Unsigned:
 	actual = new Uint64( 1234 );
 	expected = '<Uint64>';
 	t.strictEqual( compareValues( actual, expected ), null, 'returns expected value' );
@@ -510,6 +556,26 @@
 	msg = 'Expected entries [5678n], but observed [1234n]';
 	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
 
+	actual = new Uint64( 1234 );
+	expected = '<Int64>';
+	msg = 'Expected a <Int64>, but received: `1234`'; // FIXME: `1234` doesn't seem right in this context, we should mention received `Uint64`
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Uint64( 1234 );
+	expected = '<Int64>[ 1234n ]';
+	msg = 'Expected instance type <Int64>, but observed <Uint64>';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Uint64( 1234 );
+	expected = '<Something>';
+	msg = null; // FIXME: this should not return null, it's a false negative
+	t.strictEqual( compareValues( actual, expected ), null, 'returns expected message' );
+
+	actual = new Uint64( 1234 );
+	expected = '<Something>[ 1234n ]';
+	msg = 'Expected instance type <Something>, but observed <Uint64>';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
 	actual = new Uint64( 1234 );
 	expected = '<Complex128>[ 2.0, 3.0 ]';
 	msg = 'Expected instance type <Complex128>, but observed <Uint64>';

lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/lib/main.js

@@ -32,6 +32,7 @@ var isComplex = require( '@stdlib/assert/is-complex' );
 var isComplexTypedArray = require( '@stdlib/assert/is-complex-typed-array' );
 var isError = require( '@stdlib/assert/is-error' );
 var isInfinite = require( '@stdlib/assert/is-infinite' );
+var isInt64 = require( '@stdlib/assert/is-int64' );
 var isInteger = require( '@stdlib/assert/is-integer' );
 var isnan = require( '@stdlib/assert/is-nan' );
 var isNull = require( '@stdlib/assert/is-null' );
@@ -166,15 +167,21 @@ function complexAnnotation( actual, opts ) {
 }
 
 /**
-* Creates a return annotation for an unsigned 64-bit integer.
+* Creates a return annotation for a 64-bit (signed or unsigned) integer.
 *
 * @private
 * @param {*} actual - actual return value
 * @param {Object} opts - function options
-* @returns {string} return annotation for unsigned 64-bit integer
+* @returns {string} return annotation for 64-bit integer
 */
-function uint64Annotation( actual, opts ) {
-	return '<'+actual.constructor.name+'>[ '+primitiveAnnotation( actual.valueOf(), opts )+' ]';
+function int64Annotation( actual, opts ) {
+	var str = primitiveAnnotation( actual.valueOf(), opts );
+
+	// Accommodate environments not supporting native BigInts...
+	if ( str[ str.length-1 ] !== 'n' ) {
+		str += 'n';
+	}
+	return '<'+actual.constructor.name+'>[ '+str+' ]';
 }
 
 /**
@@ -198,10 +205,10 @@ function genericAnnotation( actual, opts ) {
 	if ( isComplex( actual ) ) {
 		return complexAnnotation( actual, opts );
 	}
-	if ( isUint64( actual ) ) {
-		return uint64Annotation( actual, opts );
+	if ( isInt64( actual ) || isUint64( actual ) ) {
+		return int64Annotation( actual, opts );
 	}
-	if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) {
+	if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) { // eslint-disable-line max-len
 		out = '<'+actual.constructor.name+'>';
 		if ( actual.length === 0 ) {
 			out += '[]';

lib/node_modules/@stdlib/_tools/doctest/create-annotation-value/test/test.js

@@ -37,6 +37,7 @@
 var Complex128 = require( '@stdlib/complex/float64/ctor' );
 var Complex64Array = require( '@stdlib/array/complex64' );
 var Complex128Array = require( '@stdlib/array/complex128' );
+var Int64 = require( '@stdlib/number/int64/ctor' );
 var Uint64 = require( '@stdlib/number/uint64/ctor' );
 var BooleanArray = require( '@stdlib/array/bool' );
 var createAnnotationValue = require( './../lib' );
@@ -365,14 +366,14 @@
 	t.strictEqual( createAnnotationValue( val, opts ), expected, 'returns expected value' );
 
 	if ( HAS_BIGINT64ARRAY ) {
 		// FIXME: update once we have `array/bigint64`
 		val = new BigInt64Array( [ BigInt( 100 ), BigInt( -101 ) ] ); // eslint-disable-line stdlib/require-globals, no-undef
 		expected = '<BigInt64Array>[ 100n, -101n ]';
 		t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
 	}
 
 	if ( HAS_BIGUINT64ARRAY ) {
 		// FIXME: update once we have `array/biguint64`
 		val = new BigUint64Array( [ BigInt( 100 ), BigInt( 101 ) ] ); // eslint-disable-line stdlib/require-globals, no-undef
 		expected = '<BigUint64Array>[ 100n, 101n ]';
 		t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
@@ -396,13 +397,20 @@
 	t.end();
 });
 
-tape( 'the function creates a deep instance equality annotation value for unsigned 64-bit integers', function test( t ) {
+tape( 'the function creates a deep instance equality annotation value for 64-bit (signed or unsigned) integers', function test( t ) {
 	var expected;
 	var val;
 
+	val = new Int64( 1234 );
+	expected = '<Int64>[ 1234n ]';
+	t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
+	val = new Uint64( 1234 );
+	expected = '<Uint64>[ 1234n ]';
+	t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
+
 	if ( HAS_BIGINTS ) {
-		val = new Uint64( 1234 );
-		expected = '<Uint64>[ 1234n ]';
+		val = new Int64( BigInt( '9223372036854775807' ) ); // 2^63 - 1
+		expected = '<Int64>[ 9223372036854775807n ]';
 		t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
 
 		val = new Uint64( BigInt( '18446744073709551615' ) ); // 2^64 - 1
@@ -500,14 +508,14 @@
 	t.strictEqual( createAnnotationValue( actual, opts ), expected, 'returns expected value' );
 
 	if ( HAS_BIGINT64ARRAY ) {
 		// FIXME: update once we have `array/bigint64`
 		actual = new BigInt64Array( [ BigInt( 100 ), BigInt( -101 ) ] ); // eslint-disable-line stdlib/require-globals, no-undef
 		expected = '<BigInt64Array>';
 		t.strictEqual( createAnnotationValue( actual, opts ), expected, 'returns expected value' );
 	}
 
 	if ( HAS_BIGUINT64ARRAY ) {
 		// FIXME: update once we have `array/biguint64`
 		actual = new BigUint64Array( [ BigInt( 100 ), BigInt( 101 ) ] ); // eslint-disable-line stdlib/require-globals, no-undef
 		expected = '<BigUint64Array>';
 		t.strictEqual( createAnnotationValue( actual, opts ), expected, 'returns expected value' );