mirror of
https://github.com/openjdk/jdk.git
synced 2025-08-28 23:34:52 +02:00
8261123: Augment discussion of equivalence classes in Object.equals and comparison methods
Reviewed-by: bpb, smarks, rriggs
This commit is contained in:
Joe Darcy
parent
2677f6f47d
commit
d547e1a847
4 changed files with 135 additions and 99 deletions
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 1997, 2018, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 1997, 2021, Oracle and/or its affiliates. All rights reserved.
|
||||
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
||||
*
|
||||
* This code is free software; you can redistribute it and/or modify it
|
||||
|
|
@ -62,11 +62,15 @@ import java.util.*;
|
|||
* because {@code a} and {@code b} are equivalent from the sorted set's
|
||||
* perspective.<p>
|
||||
*
|
||||
* Virtually all Java core classes that implement {@code Comparable} have natural
|
||||
* orderings that are consistent with equals. One exception is
|
||||
* {@code java.math.BigDecimal}, whose natural ordering equates
|
||||
* {@code BigDecimal} objects with equal values and different precisions
|
||||
* (such as 4.0 and 4.00).<p>
|
||||
* Virtually all Java core classes that implement {@code Comparable}
|
||||
* have natural orderings that are consistent with equals. One
|
||||
* exception is {@link java.math.BigDecimal}, whose {@linkplain
|
||||
* java.math.BigDecimal#compareTo natural ordering} equates {@code
|
||||
* BigDecimal} objects with equal numerical values and different
|
||||
* representations (such as 4.0 and 4.00). For {@link
|
||||
* java.math.BigDecimal#equals BigDecimal.equals()} to return true,
|
||||
* the representation and numerical value of the two {@code
|
||||
* BigDecimal} objects must be the same.<p>
|
||||
*
|
||||
* For the mathematically inclined, the <i>relation</i> that defines
|
||||
* the natural ordering on a given class C is:<pre>{@code
|
||||
|
|
@ -83,7 +87,12 @@ import java.util.*;
|
|||
* the class's {@link Object#equals(Object) equals(Object)} method:<pre>
|
||||
* {(x, y) such that x.equals(y)}. </pre><p>
|
||||
*
|
||||
* This interface is a member of the
|
||||
* In other words, when a class's natural ordering is consistent with
|
||||
* equals, the equivalence classes defined by the equivalence relation
|
||||
* of the {@code equals} method and the equivalence classes defined by
|
||||
* the quotient of the {@code compareTo} method are the same.
|
||||
*
|
||||
* <p>This interface is a member of the
|
||||
* <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
|
||||
* Java Collections Framework</a>.
|
||||
*
|
||||
|
|
@ -99,33 +108,28 @@ public interface Comparable<T> {
|
|||
* negative integer, zero, or a positive integer as this object is less
|
||||
* than, equal to, or greater than the specified object.
|
||||
*
|
||||
* <p>The implementor must ensure
|
||||
* {@code sgn(x.compareTo(y)) == -sgn(y.compareTo(x))}
|
||||
* for all {@code x} and {@code y}. (This
|
||||
* implies that {@code x.compareTo(y)} must throw an exception iff
|
||||
* {@code y.compareTo(x)} throws an exception.)
|
||||
* <p>The implementor must ensure {@link Integer#signum
|
||||
* signum}{@code (x.compareTo(y)) == -signum(y.compareTo(x))} for
|
||||
* all {@code x} and {@code y}. (This implies that {@code
|
||||
* x.compareTo(y)} must throw an exception if and only if {@code
|
||||
* y.compareTo(x)} throws an exception.)
|
||||
*
|
||||
* <p>The implementor must also ensure that the relation is transitive:
|
||||
* {@code (x.compareTo(y) > 0 && y.compareTo(z) > 0)} implies
|
||||
* {@code x.compareTo(z) > 0}.
|
||||
*
|
||||
* <p>Finally, the implementor must ensure that {@code x.compareTo(y)==0}
|
||||
* implies that {@code sgn(x.compareTo(z)) == sgn(y.compareTo(z))}, for
|
||||
* all {@code z}.
|
||||
* <p>Finally, the implementor must ensure that {@code
|
||||
* x.compareTo(y)==0} implies that {@code signum(x.compareTo(z))
|
||||
* == signum(y.compareTo(z))}, for all {@code z}.
|
||||
*
|
||||
* <p>It is strongly recommended, but <i>not</i> strictly required that
|
||||
* @apiNote
|
||||
* It is strongly recommended, but <i>not</i> strictly required that
|
||||
* {@code (x.compareTo(y)==0) == (x.equals(y))}. Generally speaking, any
|
||||
* class that implements the {@code Comparable} interface and violates
|
||||
* this condition should clearly indicate this fact. The recommended
|
||||
* language is "Note: this class has a natural ordering that is
|
||||
* inconsistent with equals."
|
||||
*
|
||||
* <p>In the foregoing description, the notation
|
||||
* {@code sgn(}<i>expression</i>{@code )} designates the mathematical
|
||||
* <i>signum</i> function, which is defined to return one of {@code -1},
|
||||
* {@code 0}, or {@code 1} according to whether the value of
|
||||
* <i>expression</i> is negative, zero, or positive, respectively.
|
||||
*
|
||||
* @param o the object to be compared.
|
||||
* @return a negative integer, zero, or a positive integer as this object
|
||||
* is less than, equal to, or greater than the specified object.
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
/*
|
||||
* Copyright (c) 1994, 2020, Oracle and/or its affiliates. All rights reserved.
|
||||
* Copyright (c) 1994, 2021, Oracle and/or its affiliates. All rights reserved.
|
||||
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
||||
*
|
||||
* This code is free software; you can redistribute it and/or modify it
|
||||
|
|
@ -78,15 +78,16 @@ public class Object {
|
|||
* used in {@code equals} comparisons on the object is modified.
|
||||
* This integer need not remain consistent from one execution of an
|
||||
* application to another execution of the same application.
|
||||
* <li>If two objects are equal according to the {@code equals(Object)}
|
||||
* method, then calling the {@code hashCode} method on each of
|
||||
* the two objects must produce the same integer result.
|
||||
* <li>If two objects are equal according to the {@link
|
||||
* equals(Object) equals} method, then calling the {@code
|
||||
* hashCode} method on each of the two objects must produce the
|
||||
* same integer result.
|
||||
* <li>It is <em>not</em> required that if two objects are unequal
|
||||
* according to the {@link java.lang.Object#equals(java.lang.Object)}
|
||||
* method, then calling the {@code hashCode} method on each of the
|
||||
* two objects must produce distinct integer results. However, the
|
||||
* programmer should be aware that producing distinct integer results
|
||||
* for unequal objects may improve the performance of hash tables.
|
||||
* according to the {@link equals(Object) equals} method, then
|
||||
* calling the {@code hashCode} method on each of the two objects
|
||||
* must produce distinct integer results. However, the programmer
|
||||
* should be aware that producing distinct integer results for
|
||||
* unequal objects may improve the performance of hash tables.
|
||||
* </ul>
|
||||
*
|
||||
* @implSpec
|
||||
|
|
@ -127,15 +128,27 @@ public class Object {
|
|||
* <li>For any non-null reference value {@code x},
|
||||
* {@code x.equals(null)} should return {@code false}.
|
||||
* </ul>
|
||||
*
|
||||
* <p>
|
||||
* An equivalence relation partitions the elements it operates on
|
||||
* into <i>equivalence classes</i>; all the members of an
|
||||
* equivalence class are equal to each other. Members of an
|
||||
* equivalence class are substitutable for each other, at least
|
||||
* for some purposes.
|
||||
*
|
||||
* @implSpec
|
||||
* The {@code equals} method for class {@code Object} implements
|
||||
* the most discriminating possible equivalence relation on objects;
|
||||
* that is, for any non-null reference values {@code x} and
|
||||
* {@code y}, this method returns {@code true} if and only
|
||||
* if {@code x} and {@code y} refer to the same object
|
||||
* ({@code x == y} has the value {@code true}).
|
||||
* <p>
|
||||
* Note that it is generally necessary to override the {@code hashCode}
|
||||
*
|
||||
* In other words, under the reference equality equivalence
|
||||
* relation, each equivalence class only has a single element.
|
||||
*
|
||||
* @apiNote
|
||||
* It is generally necessary to override the {@link hashCode hashCode}
|
||||
* method whenever this method is overridden, so as to maintain the
|
||||
* general contract for the {@code hashCode} method, which states
|
||||
* that equal objects must have equal hash codes.
|
||||
|
|
@ -183,7 +196,8 @@ public class Object {
|
|||
* primitive fields or references to immutable objects, then it is usually
|
||||
* the case that no fields in the object returned by {@code super.clone}
|
||||
* need to be modified.
|
||||
* <p>
|
||||
*
|
||||
* @implSpec
|
||||
* The method {@code clone} for class {@code Object} performs a
|
||||
* specific cloning operation. First, if the class of this object does
|
||||
* not implement the interface {@code Cloneable}, then a
|
||||
|
|
@ -214,13 +228,17 @@ public class Object {
|
|||
protected native Object clone() throws CloneNotSupportedException;
|
||||
|
||||
/**
|
||||
* Returns a string representation of the object. In general, the
|
||||
* Returns a string representation of the object.
|
||||
* @apiNote
|
||||
* In general, the
|
||||
* {@code toString} method returns a string that
|
||||
* "textually represents" this object. The result should
|
||||
* be a concise but informative representation that is easy for a
|
||||
* person to read.
|
||||
* It is recommended that all subclasses override this method.
|
||||
* <p>
|
||||
* The string output is not necessarily stable over time or across
|
||||
* JVM invocations.
|
||||
* @implSpec
|
||||
* The {@code toString} method for class {@code Object}
|
||||
* returns a string consisting of the name of the class of which the
|
||||
* object is an instance, the at-sign character `{@code @}', and
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue