[type-classes] 8376040: Add prototype "textbook complex" class

[jddarcy]

First cut at a version of complex numbers using the textbook algorithms for the arithmetic operations. This version is intended for prototyping and not for production use.

---

Progress

• Change must not contain extraneous whitespace

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/valhalla.git pull/1942/head:pull/1942
$ git checkout pull/1942

Update a local copy of the PR:
$ git checkout pull/1942
$ git pull https://git.openjdk.org/valhalla.git pull/1942/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 1942

View PR using the GUI difftool:
$ git pr show -t 1942

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/valhalla/pull/1942.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back darcy! A progress list of the required criteria for merging this PR into type-classes will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@jddarcy This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

[type-classes] 8376040: Add prototype "textbook complex" class

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 2 new commits pushed to the type-classes branch:

• ddd948a: [type-classes]: Lowered code for operator for type class operators is missing a cast
• 6a6f75c: [type-classes] Initial work to enable type-classes mediated operator support

Please see this link for an up-to-date comparison between the source branch of this pull request and the type-classes branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the type-classes branch, type /integrate in a new comment.

[jddarcy]

Since the HTML markup in the javadoc for the arithmetic methods is hard to read, here is a copy and paste of the rendered text:

public static ComplexTextbook add(ComplexTextbook addend, ComplexTextbook augend)

Addition operation, binary "+".

Implementation Requirements:
The computed sum is equivalent to (a + c) + i·(b + d).

public static ComplexTextbook subtract(ComplexTextbook minuend, ComplexTextbook subtrahend)

Subtraction operation, binary "-".

Implementation Requirements:
The computed difference is equivalent to (a − c) + i·(b − d).

public static ComplexTextbook multiply(ComplexTextbook multiplier, ComplexTextbook multiplicand)

Multiplication operation, "*".

API Note:
WARNING: while simple, the calculation technique used by this method is subject to spurious underflow and overflow as well as inaccurate component-wise results.
Implementation Requirements:
The computed product is calculated by (ac − bd) + i·(ad + bc)

public static ComplexTextbook divide(ComplexTextbook dividend, ComplexTextbook divisor)

Division operation, "/".

API Note:
TODO: Bad numerical things can happen warning...
Implementation Requirements:
The computed quotient is calculated by (ac + bd)/(c² + d²) + i*(bc − ad)/(c² + d²)

[mlbridge]

Webrevs

• 01: Full - Incremental (028b54af)
• 00: Full (03baac7f)

[rgiulietti]

Suggested change

	if (that instanceof ComplexTextbook c) {
	return this.real == c.real && this.imag == c.imag;
	} else {
	return false;
	}
	return that instanceof ComplexTextbook c && real == c.real && imag == c.imag;

[jddarcy]

Done; I'll make any other necessary adjustments to the java.lang.Object methods when adding support for overloaded operators.

[rgiulietti]

Since we have abs(), is there a reason for not having theta() (or arg(), or whatever)?

[jddarcy]

Those could be added in a subsequent iteration, sure.

[rgiulietti]

Besides being shorter and unambiguous, re() and im() are the standard names used in maths AFAIK.

[jddarcy]

Hmm.
I'd prefer to leave the more idiomatic or Java "real" and "imag" for now, but acknowledged "re" and "im" are common in other contexts.

[jddarcy]

/integrate

[openjdk]

Going to push as commit da76b22.
Since your change was applied there have been 2 commits pushed to the type-classes branch:

• ddd948a: [type-classes]: Lowered code for operator for type class operators is missing a cast
• 6a6f75c: [type-classes] Initial work to enable type-classes mediated operator support

Your commit was automatically rebased without conflicts.

[openjdk]

@jddarcy Pushed as commit da76b22.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.