feat: add support for comparing complex number entries

---
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: na
  - task: lint_package_json
    status: na
  - task: lint_repl_help
    status: na
  - task: lint_javascript_src
    status: passed
  - task: lint_javascript_cli
    status: na
  - task: lint_javascript_examples
    status: na
  - task: lint_javascript_tests
    status: passed
  - task: lint_javascript_benchmarks
    status: na
  - 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: na
  - task: lint_typescript_tests
    status: na
  - task: lint_license_headers
    status: passed
---

---
type: pre_push_report
description: Results of running various checks prior to pushing changes.
report:
  - task: run_javascript_examples
    status: na
  - task: run_c_examples
    status: na
  - task: run_cpp_examples
    status: na
  - task: run_javascript_readme_examples
    status: na
  - task: run_c_benchmarks
    status: na
  - task: run_cpp_benchmarks
    status: na
  - task: run_fortran_benchmarks
    status: na
  - task: run_javascript_benchmarks
    status: na
  - task: run_julia_benchmarks
    status: na
  - task: run_python_benchmarks
    status: na
  - task: run_r_benchmarks
    status: na
  - task: run_javascript_tests
    status: passed
---

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

@@ -30,6 +30,8 @@ var deepEqual = require( '@stdlib/assert/deep-equal' );
 var isArray = require( '@stdlib/assert/is-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 isBooleanArray = require( '@stdlib/assert/is-booleanarray' );
 var isBoxedPrimitive = require( '@stdlib/assert/is-boxed-primitive' );
@@ -44,7 +46,12 @@ 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' );
@@ -62,6 +69,10 @@ var isSymbol = require( '@stdlib/assert/is-symbol' );
 var isSyntaxError = require( '@stdlib/assert/is-syntax-error' );
 var isTypedArray = require( '@stdlib/assert/is-typed-array' );
 var isTypeError = require( '@stdlib/assert/is-type-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' );
 
@@ -74,6 +85,10 @@ 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' );
@@ -182,9 +197,15 @@ function checkForPlaceholders( actual, expected ) {
 		return isArrayBuffer( actual );
 	case '<BigInt>':
 		return isBigInt( actual );
+	case '<BigInt64Array>':
+		return isBigInt64Array( actual );
+	case '<BigUint64Array>':
+		return isBigUint64Array( actual );
 	case '<boolean>':
 	case '<Boolean>':
 		return isBoolean( actual );
+	case '<BooleanArray>':
+		return isBooleanArray( actual );
 	case '<Buffer>':
 		return isBuffer( actual );
 	case '<Complex64>':
@@ -203,8 +224,18 @@ function checkForPlaceholders( actual, expected ) {
 		return isError( actual );
 	case '<EvalError>':
 		return isEvalError( actual );
+	case '<Float32Array>':
+		return isFloat32Array( actual );
+	case '<Float64Array>':
+		return isFloat64Array( actual );
 	case '<Function>':
 		return isFunction( actual );
+	case '<Int8Array>':
+		return isInt8Array( actual );
+	case '<Int16Array>':
+		return isInt16Array( actual );
+	case '<Int32Array>':
+		return isInt32Array( actual );
 	case '<MultiSlice>':
 		return isMultiSlice( actual );
 	case '<ndarray>':
@@ -237,12 +268,20 @@ function checkForPlaceholders( actual, expected ) {
 		return isTypeError( actual );
 	case '<TypedArray>':
 		return isTypedArray( actual );
+	case '<Uint8Array>':
+		return isUint8Array( actual );
+	case '<Uint8ClampedArray>':
+		return isUint8ClampedArray( actual );
+	case '<Uint16Array>':
+		return isUint16Array( actual );
+	case '<Uint32Array>':
+		return isUint32Array( actual );
 	case '<URIError>':
 		return isURIError( actual );
 	default:
 		// Unknown type, let it slide...
 
-		// FIXME: should we compare constructor names here at a minimum?
+		// TODO: should we compare constructor names here at a minimum?
 		return true;
 	}
 }
@@ -269,12 +308,50 @@ function compareEntries( actual, expected ) {
 }
 
 /**
-* 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.
+* 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 <'+actual.constructor.name+'>, but observed <'+type+'>';
+		}
+		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;
@@ -455,6 +532,9 @@ function compareValues( actual, expected ) {
 		}
 		return null;
 	}
+	if ( isComplex64( actual ) || isComplex128( actual ) ) {
+		return checkComplex( actual, expected );
+	}
 	if ( isRegExp( actual ) ) {
 		actual = actual.toString();
 		if ( actual !== expected ) {

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

@@ -329,6 +329,40 @@ tape( 'the function compares a typed array and a corresponding return annotation
 	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 = '<Complex64>';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );
+
+	actual = new Complex64( 2.0, 3.0 );
+	expected = '<Complex64>[ 2.0, 3.0 ]';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );
+
+	actual = new Complex64( 2.0, 3.0 );
+	expected = '<Complex64>[ 2.0, 4.0 ]';
+	msg = 'Expected array entries [2,4], but observed [2,3]';
+	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
+
+	actual = new Complex128( 2.0, 3.0 );
+	expected = '<Complex128>';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );
+
+	actual = new Complex128( 2.0, 3.0 );
+	expected = '<Complex128>[ 2.0, 3.0 ]';
+	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );
+
+	actual = new Complex128( 2.0, 3.0 );
+	expected = '<Complex128>[ 2.0, 4.0 ]';
+	msg = 'Expected array entries [2,4], but observed [2,3]';
+	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;
@@ -362,14 +396,6 @@ tape( 'the function compares a value with a type equality return annotation', fu
 	msg = 'Expected a <boolean>, but received: `0`';
 	t.strictEqual( compareValues( actual, expected ), msg, 'returns expected message' );
 
-	actual = new Complex64( 2.0, 3.0 );
-	expected = '<Complex64>';
-	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );
-
-	actual = new Complex128( 2.0, 3.0 );
-	expected = '<Complex128>';
-	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );
-
 	actual = new ArrayBuffer( 10 );
 	expected = '<ArrayBuffer>';
 	t.strictEqual( compareValues( actual, expected ), null, 'returns null' );