diff options
Diffstat (limited to 'libjava/java/lang/Comparable.java')
| -rw-r--r-- | libjava/java/lang/Comparable.java | 72 |
1 files changed, 50 insertions, 22 deletions
diff --git a/libjava/java/lang/Comparable.java b/libjava/java/lang/Comparable.java index e1e5b1b..96d4d6a 100644 --- a/libjava/java/lang/Comparable.java +++ b/libjava/java/lang/Comparable.java @@ -1,5 +1,5 @@ /* Comparable.java -- Interface for comparaing objects to obtain an ordering - Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc. + Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -7,7 +7,7 @@ GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. - + GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU @@ -38,32 +38,60 @@ exception statement from your version. */ package java.lang; -/* Written using online API docs for JDK 1.2 beta from http://www.javasoft.com. - * Status: Believed complete and correct. - */ - -/** - * Interface for objects that can be ordering among other - * objects. The ordering can be <EM>total</EM>, such that two objects - * only compare equal if they are equal by the equals method, or - * <EM>partial</EM> such that this is not necessarily true. For - * example, a case-sensitive dictionary order comparison of Strings - * is total, but if it is case-insensitive it is partial, because - * "abc" and "ABC" compare as equal even though "abc".equals("ABC") - * returns false. +/** + * Interface for objects that can be ordering among other objects. The + * ordering can be <em>total</em>, such that two objects only compare equal + * if they are also equal by the equals method, or <em>partial</em> such + * that this is not necessarily true. For example, a case-sensitive + * dictionary order comparison of Strings is total, but if it is + * case-insensitive it is partial, because "abc" and "ABC" compare as + * equal even though "abc".equals("ABC") returns false. However, if you use + * a partial ordering, it is a good idea to document your class as + * "inconsistent with equals", because the behavior of your class in a + * SortedMap will be different than in a HashMap. + * + * <p>Lists, arrays, and sets of objects that implement this interface can + * be sorted automatically, without the need for an explicit + * {@link Comparator}. Note that <code>e1.compareTo(null)</code> should + * throw an Exception; as should comparison between incompatible classes. * * @author Geoff Berry * @author Warren Levy <warrenl@cygnus.com> - * - * @since JDK1.2 - * @see java.util.Comparator + * @see Comparator + * @see Collections#sort(List) + * @see Arrays#sort(Object[]) + * @see SortedSet + * @see SortedMap + * @see TreeSet + * @see TreeMap + * @since 1.2 + * @status updated to 1.4 */ public interface Comparable { /** - * @return a negative integer if this object is less than - * <code>o<code>, zero if this object is equal to <code>o</code>, or - * a positive integer if this object is greater than <code>o</code> + * Compares this object with another, and returns a numerical result based + * on the comparison. If the result is negative, this object sorts less + * than the other; if 0, the two are equal, and if positive, this object + * sorts greater than the other. To translate this into boolean, simply + * perform <code>o1.compareTo(o2) <em><op></em> 0</code>, where op + * is one of <, <=, =, !=, >, or >=. + * + * <p>You must make sure that the comparison is mutual, ie. + * <code>sgn(x.compareTo(y)) == -sgn(y.compareTo(x))</code> (where sgn() is + * defined as -1, 0, or 1 based on the sign). This includes throwing an + * exception in either direction if the two are not comparable; hence, + * <code>compareTo(null)</code> should always throw an Exception. + * + * <p>You should also ensure transitivity, in two forms: + * <code>x.compareTo(y) > 0 && y.compareTo(z) > 0</code> implies + * <code>x.compareTo(z) > 0</code>; and <code>x.compareTo(y) == 0</code> + * implies <code>x.compareTo(z) == y.compareTo(z)</code>. + * + * @param o the object to be compared + * @return an integer describing the comparison + * @throws NullPointerException if o is null + * @throws ClassCastException if o cannot be compared */ - int compareTo( Object o ); + int compareTo(Object o); } |