]>
Commit | Line | Data |
---|---|---|
cfcdbe54 | 1 | /* Comparable.java -- Interface for comparaing objects to obtain an ordering |
3e1b181a | 2 | Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc. |
ee9dd372 | 3 | |
cfcdbe54 | 4 | This file is part of GNU Classpath. |
ee9dd372 | 5 | |
cfcdbe54 MW |
6 | GNU Classpath is free software; you can redistribute it and/or modify |
7 | it under the terms of the GNU General Public License as published by | |
8 | the Free Software Foundation; either version 2, or (at your option) | |
9 | any later version. | |
3e1b181a | 10 | |
cfcdbe54 MW |
11 | GNU Classpath is distributed in the hope that it will be useful, but |
12 | WITHOUT ANY WARRANTY; without even the implied warranty of | |
13 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
14 | General Public License for more details. | |
15 | ||
16 | You should have received a copy of the GNU General Public License | |
17 | along with GNU Classpath; see the file COPYING. If not, write to the | |
18 | Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA | |
19 | 02111-1307 USA. | |
20 | ||
92aaa246 MW |
21 | Linking this library statically or dynamically with other modules is |
22 | making a combined work based on this library. Thus, the terms and | |
23 | conditions of the GNU General Public License cover the whole | |
24 | combination. | |
25 | ||
26 | As a special exception, the copyright holders of this library give you | |
27 | permission to link this library with independent modules to produce an | |
28 | executable, regardless of the license terms of these independent | |
29 | modules, and to copy and distribute the resulting executable under | |
30 | terms of your choice, provided that you also meet, for each linked | |
31 | independent module, the terms and conditions of the license of that | |
32 | module. An independent module is a module which is not derived from | |
33 | or based on this library. If you modify this library, you may extend | |
34 | this exception to your version of the library, but you are not | |
35 | obligated to do so. If you do not wish to do so, delete this | |
36 | exception statement from your version. */ | |
cfcdbe54 MW |
37 | |
38 | ||
ee9dd372 | 39 | package java.lang; |
cfcdbe54 | 40 | |
3e1b181a TT |
41 | /** |
42 | * Interface for objects that can be ordering among other objects. The | |
43 | * ordering can be <em>total</em>, such that two objects only compare equal | |
44 | * if they are also equal by the equals method, or <em>partial</em> such | |
45 | * that this is not necessarily true. For example, a case-sensitive | |
46 | * dictionary order comparison of Strings is total, but if it is | |
47 | * case-insensitive it is partial, because "abc" and "ABC" compare as | |
48 | * equal even though "abc".equals("ABC") returns false. However, if you use | |
49 | * a partial ordering, it is a good idea to document your class as | |
50 | * "inconsistent with equals", because the behavior of your class in a | |
51 | * SortedMap will be different than in a HashMap. | |
52 | * | |
53 | * <p>Lists, arrays, and sets of objects that implement this interface can | |
54 | * be sorted automatically, without the need for an explicit | |
4166b036 AT |
55 | * {@link java.util.Comparator}. Note that <code>e1.compareTo(null)</code> |
56 | * should throw an Exception; as should comparison between incompatible | |
57 | * classes. | |
cfcdbe54 MW |
58 | * |
59 | * @author Geoff Berry | |
60 | * @author Warren Levy <warrenl@cygnus.com> | |
4166b036 AT |
61 | * @see java.util.Comparator |
62 | * @see java.util.Collections#sort(java.util.List) | |
63 | * @see java.util.Arrays#sort(Object[]) | |
64 | * @see java.util.SortedSet | |
65 | * @see java.util.SortedMap | |
66 | * @see java.util.TreeSet | |
67 | * @see java.util.TreeMap | |
3e1b181a TT |
68 | * @since 1.2 |
69 | * @status updated to 1.4 | |
cfcdbe54 | 70 | */ |
ee9dd372 TT |
71 | public interface Comparable |
72 | { | |
cfcdbe54 | 73 | /** |
3e1b181a TT |
74 | * Compares this object with another, and returns a numerical result based |
75 | * on the comparison. If the result is negative, this object sorts less | |
76 | * than the other; if 0, the two are equal, and if positive, this object | |
77 | * sorts greater than the other. To translate this into boolean, simply | |
78 | * perform <code>o1.compareTo(o2) <em><op></em> 0</code>, where op | |
79 | * is one of <, <=, =, !=, >, or >=. | |
80 | * | |
81 | * <p>You must make sure that the comparison is mutual, ie. | |
82 | * <code>sgn(x.compareTo(y)) == -sgn(y.compareTo(x))</code> (where sgn() is | |
83 | * defined as -1, 0, or 1 based on the sign). This includes throwing an | |
84 | * exception in either direction if the two are not comparable; hence, | |
85 | * <code>compareTo(null)</code> should always throw an Exception. | |
86 | * | |
87 | * <p>You should also ensure transitivity, in two forms: | |
88 | * <code>x.compareTo(y) > 0 && y.compareTo(z) > 0</code> implies | |
89 | * <code>x.compareTo(z) > 0</code>; and <code>x.compareTo(y) == 0</code> | |
90 | * implies <code>x.compareTo(z) == y.compareTo(z)</code>. | |
91 | * | |
92 | * @param o the object to be compared | |
93 | * @return an integer describing the comparison | |
94 | * @throws NullPointerException if o is null | |
95 | * @throws ClassCastException if o cannot be compared | |
cfcdbe54 | 96 | */ |
3e1b181a | 97 | int compareTo(Object o); |
ee9dd372 | 98 | } |