feat: add doctest support for Uint64

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

@@ -26,6 +26,7 @@
 var epsdiff = require( '@stdlib/math/base/utils/float64-epsilon-difference' );
 var indexOf = require( '@stdlib/array/base/index-of' );
 var typeOf = require( '@stdlib/utils/type-of' );
+var map = require( '@stdlib/array/base/map' );
 var deepEqual = require( '@stdlib/assert/deep-equal' );
 
 // Note: keep in alphabetical order
@@ -77,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 isUint64 = require( '@stdlib/assert/is-uint64' );
 var isUndefined = require( '@stdlib/assert/is-undefined' );
 var isURIError = require( '@stdlib/assert/is-uri-error' );
 
@@ -323,12 +325,14 @@
 		return isUint16Array( actual );
 	case '<Uint32Array>':
 		return isUint32Array( actual );
+	case '<Uint64>':
+		return isUint64( actual );
 	case '<URIError>':
 		return isURIError( actual );
 	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;
 	}
 }
@@ -344,11 +348,11 @@
 function compareEntries( actual, expected ) {
 	var i;
 	if ( actual.length !== expected.length ) {
-		return format( 'Expected entries [%s], but observed [%s]', expected, actual );
+		return format( 'Expected entries [%s], but observed [%s]', map( expected, formatValue ), map( actual, formatValue ) );
 	}
 	for ( i = 0; i < expected.length; i++ ) {
 		if ( !checkPrimitive( actual[ i ], expected[ i ] ) ) {
-			return format( 'Expected entries [%s], but observed [%s]', expected, actual );
+			return format( 'Expected entries [%s], but observed [%s]', map( expected, formatValue ), map( actual, formatValue ) );
 		}
 	}
 	return null;
@@ -381,12 +385,41 @@
 				actual = [ realf( actual ), imagf( actual ) ];
 			}
 			return compareEntries( actual, parse( entries ) );
 		}
 		return null;
 	}
 	return 'Complex numbers should be documented using instance annotation';
 }
 
+/**
+* Checks whether an unsigned 64-bit 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 ) {
+	var entries;
+	var match;
+	var type;
+
+	match = RE_INSTANCE_ANNOTATION.exec( expected );
+	if ( match ) {
+		type = match[ 1 ];
+		entries = match[ 2 ];
+		if ( constructorName( actual ) !== type ) {
+			return format( 'Expected instance type <%s>, but observed <%s>', type, constructorName( actual ) );
+		}
+		if ( entries ) {
+			actual = [ actual.valueOf() ];
+			return compareEntries( actual, parse( entries ) );
+		}
+		return null;
+	}
+	return 'Unsigned 64-bit integers should be documented using instance annotation';
+}
+
 /**
 * Checks whether a typed array matches the expected return annotation.
 *
@@ -634,6 +667,10 @@
 	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( array( [ 1.0, 2.0 ] ), '<ndarray>[ 1.0, 2.0 ]' )
 	if ( isndarrayLike( actual ) ) {
 		return checkNDArray( actual, expected );

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 Uint64 = require( '@stdlib/number/uint64/ctor' );
 var Boolean = require( '@stdlib/boolean/ctor' );
 var BigInt = require( '@stdlib/bigint/ctor' );
 var Object = require( '@stdlib/object/ctor' );
@@ -163,7 +164,7 @@
 	t.end();
 });
 
 tape( 'the function compares an array and a corresponding return annotation', function test( t ) {
 	var expected;
 	var actual;
 	var msg;
@@ -486,6 +487,37 @@
 	t.end();
 });
 
+tape( 'the function compares an unsigned 64-bit integer and a corresponding return annotation', function test( t ) {
+	var expected;
+	var actual;
+	var msg;
+
+	actual = new Uint64( 1234 );
+	expected = '<Uint64>';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns expected value' );
+
+	actual = new Uint64( 1234 );
+	expected = '<Uint64>[ 1234n ]';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns expected value' );
+
+	actual = new Uint64( 1234 );
+	expected = '<Uint64>[ 1234 ]';
+	msg = 'Expected entries [1234], but observed [1234n]';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Uint64( 1234 );
+	expected = '<Uint64>[ 5678n ]';
+	msg = 'Expected entries [5678n], but observed [1234n]';
+	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>';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	t.end();
+});
+
 tape( 'the function compares a value with a type equality return annotation', function test( t ) {
 	var expected;
 	var actual;

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

@@ -42,6 +42,7 @@
 var isString = require( '@stdlib/assert/is-string' );
 var isTypedArray = require( '@stdlib/assert/is-typed-array' );
 var isUndefined = require( '@stdlib/assert/is-undefined' );
+var isUint64 = require( '@stdlib/assert/is-uint64' );
 var capitalize = require( '@stdlib/string/capitalize' );
 var roundn = require( '@stdlib/math/base/special/roundn' );
 var floor = require( '@stdlib/math/base/special/floor' );
@@ -164,6 +165,18 @@
 	return out;
 }
 
+/**
+* Creates a return annotation for an unsigned 64-bit integer.
+*
+* @private
+* @param {*} actual - actual return value
+* @param {Object} opts - function options
+* @returns {string} return annotation for unsigned 64-bit integer
+*/
+function uint64Annotation( actual, opts ) {
+	return '<'+actual.constructor.name+'>[ '+primitiveAnnotation( actual.valueOf(), opts )+' ]';
+}
+
 /**
 * Creates a return annotation for a JavaScript value.
 *
@@ -185,7 +198,10 @@
 	if ( isComplex( actual ) ) {
 		return complexAnnotation( actual, opts );
 	}
+	if ( isUint64( actual ) ) {
+		return uint64Annotation( actual, opts );
+	}
 	if ( isTypedArray( actual ) || isComplexTypedArray( actual ) || isBooleanArray( actual ) ) {
 		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 Uint64 = require( '@stdlib/number/uint64/ctor' );
 var BooleanArray = require( '@stdlib/array/bool' );
 var createAnnotationValue = require( './../lib' );
 
@@ -364,14 +365,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' );
@@ -395,6 +396,23 @@
 	t.end();
 });
 
+tape( 'the function creates a deep instance equality annotation value for unsigned 64-bit integers', function test( t ) {
+	var expected;
+	var val;
+
+	if ( HAS_BIGINTS ) {
+		val = new Uint64( 1234 );
+		expected = '<Uint64>[ 1234n ]';
+		t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
+
+		val = new Uint64( BigInt( '18446744073709551615' ) ); // 2^64 - 1
+		expected = '<Uint64>[ 18446744073709551615n ]';
+		t.strictEqual( createAnnotationValue( val ), expected, 'returns expected value' );
+	}
+
+	t.end();
+});
+
 tape( 'the function creates a return annotation value for plain objects', function test( t ) {
 	var expected;
 	var val;
@@ -482,14 +500,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' );