Refine Hashable and Equatable on Quaternion

[markuswntr]

• Canonical Representations
  Add canonicalized and canonicalizedTransform properties

• Equatable
  Update type and header documentation and mention the alternative for transformations in R³

• Hashable
  This PR changes the hashing behavior of Quaternion, so that any finite quaternion q clears the sign bit of its real component before hashing.

• Transform Equality
  Added a new transformEquals() method on Quaternion to test for 3D transformation equality.

[stephentyrone]

I'd like to make this more precise. If I wasn't concerned about jargon, I would say "the canonical representative of the equivalence class of quaternions representing the same 3d transformation."

[markuswntr]

"The canonical representative of quaternions with non-negative real components representing the same 3D transformation."
Does that make sense? :)

I guess that's another task to think about over the weekend.

[stephentyrone]

How do we feel about how this reads at a use site?

if q.transformEquals(p) { /* ... */ }

I don't love that "transform" may read as a verb if you don't know what you're looking at. What if we used something like this instead:

if q.equals(as3DTransform: p) { /* ... */ }

I'm not totally set on this either way, but let's give it some thought.

[markuswntr]

How do we feel about how this reads at a use site?

if q.transformEquals(p) { /* ... */ }

Yeah, you are right. This can easily be misread. We could maybe use transformationEquals to make it more explicit.

if q.equals(as3DTransform: p) { /* ... */ }

I think, I do prefer this spelling over transformEquals/transformationEquals. If we want to (somewhat) reuse existing naming patterns, we could utilize append(contentsOf:) and insert(contentsOf:at:) on Array and use:

if q.equals(transformationOf: p) { /* ... */ }

Though, I think it is a little less obvious and does not mention 3D explicitly.

[stephentyrone]

Let's think about this over the weekend and see if we can make a provisional decision on Monday.

[stephentyrone]

Any further thoughts on this? If not, let's go with equals(as3DTransform:) for now?

[NevinBR]

Perhaps q.isSame3DTransform(as: p) or some such?

[markuswntr]

I changed it to equals(as3DTransform:) for now. I think, it reads a little nicer at the call site.

[stephentyrone]

@markuswntr is this ready to merge from your perspective, or do you want to iterate on it more first?

[markuswntr]

Hi @stephentyrone, as you mentioned previously, the canonicalizedTransform property needs a more precise header comment. Other than that I think it is ready to merge.
If it is okay with you, I will provide an updated documentation later - than you can merge it as is.