Hi Jon,
Thanks for the comments; second take on the re-wording up at
http://cr.openjdk.java.net/~darcy/8234783.1/
and copied below for convenience.
Cheers,
-Joe
--- old/src/java.base/share/classes/java/lang/Record.java 2020-01-06
16:18:43.505405539 -0800
+++ new/src/java.base/share/classes/java/lang/Record.java 2020-01-06
16:18:43.317311546 -0800
@@ -92,8 +92,8 @@
public abstract class Record {
/**
* Indicates whether some other object is "equal to" this one. In
addition
- * to the general contract of {@link Object#equals(Object)},
- * record classes must further participate in the invariant that when
+ * to the general contract of {@link Object#equals(Object)
Object.equals},
+ * record classes must further obey the invariant that when
* a record instance is "copied" by passing the result of the
record component
* accessor methods to the canonical constructor, as follows:
* <pre>
@@ -102,17 +102,37 @@
* then it must be the case that {@code r.equals(copy)}.
*
* @implSpec
- * The implicitly provided implementation returns {@code true} if and
- * only if the argument is an instance of the same record type as
this object,
- * and each component of this record is equal to the corresponding
component
- * of the argument, according to {@link
java.util.Objects#equals(Object,Object)}
- * for components whose types are reference types, and according to
the semantics
- * of the {@code equals} method on the corresponding primitive
wrapper type.
+ * The implicitly provided implementation returns {@code true} if
+ * and only if the argument is an instance of the same record type
+ * as this object, and each component of this record is equal to
+ * the corresponding component of the argument; otherwise, {@code
+ * false} is returned. Equality of a component {@code c} is
+ * determined as follows:
+ * <ul>
+ *
+ * <li> If the component is of a reference type, the component is
+ * considered equal if and only if {@link
+ * java.util.Objects#equals(Object,Object)
+ * Objects.equals(this.c(), r.c()} would return {@code true}.
+ *
+ * <li> If the component is of a primitive type, using the
+ * corresponding primitive wrapper class {@code PW} (the wrapper
+ * class {@code java.lang.Integer} for {@code int}, and so on) the
+ * component is considered equal if and only if {@code
+ * PW.valueOf(this.c()).equals(PW.valueOf(r.c()))} would return
+ * {@code true}.
+ *
+ * </ul>
+ *
+ * The implicitly provided implementation conforms to the
+ * semantics described above; the implementation may or may not
+ * accomplish this by using calls to the particular methods
+ * listed.
*
* @see java.util.Objects#equals(Object,Object)
*
* @param obj the reference object with which to compare.
- * @return {@code true} if this object is the same as the obj
+ * @return {@code true} if this object is equal to the
* argument; {@code false} otherwise.
*/
@Override
On 1/6/2020 1:22 PM, Jonathan Gibbons wrote:
I like what you're trying to do, but the wording used to introduce the
names `cr` and `cp` feels a bit contorted. How about using a single
name, c, introduced up front in this line:
+ * of the argument. Equality of a component {@code c} is
determined as follows:
with the rest of the text updated accordingly. Note the use of the
indefinite article `a component` when the name is introduced, and the
definite article `the component` in subsequent references.
-- Jon
On 1/6/20 1:08 PM, Joe Darcy wrote:
Hello,
Please review a clarification to the specification of Record.equals:
JDK-8234783: Improve wording of spec of Record.equals
http://cr.openjdk.java.net/~darcy/8234783.0/
Patch below.
Thanks,
-Joe
--- old/src/java.base/share/classes/java/lang/Record.java 2020-01-06
13:00:52.179585999 -0800
+++ new/src/java.base/share/classes/java/lang/Record.java 2020-01-06
13:00:51.987681999 -0800
@@ -105,9 +105,21 @@
* The implicitly provided implementation returns {@code true}
if and
* only if the argument is an instance of the same record type
as this object,
* and each component of this record is equal to the
corresponding component
- * of the argument, according to {@link
java.util.Objects#equals(Object,Object)}
- * for components whose types are reference types, and according
to the semantics
- * of the {@code equals} method on the corresponding primitive
wrapper type.
+ * of the argument. Equality of the components is determined as
follows:
+ * <ul>
+ *
+ * <li> If the component is of a reference type, the component
{@code
+ * cr} is considered equal if and only if {@link
+ * java.util.Objects#equals(Object,Object)
+ * Objects.equals(this.cr(), r.cr()} would return true .
+ *
+ * <li> If the component is of a primitive type, using the
+ * corresponding primitive wrapper class {@code P} the component
+ * {@code cp} is considered equal if and only if {@code
+ * P.valueOf(this.cp()).equals(P.valueOf(r.cp()))} would return
+ * true.
+ *
+ * </ul>
*
* @see java.util.Objects#equals(Object,Object)
*
