01: /*
02: Copyright © 1999 CERN - European Organization for Nuclear Research.
03: Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose
04: is hereby granted without fee, provided that the above copyright notice appear in all copies and
05: that both that copyright notice and this permission notice appear in supporting documentation.
06: CERN makes no representations about the suitability of this software for any purpose.
07: It is provided "as is" without expressed or implied warranty.
08: */
09:
10: package org.hammurapi.inspectors.metrics.statistics;
11:
12: /**
13: * A comparison function which imposes a <i>total ordering</i> on some
14: * collection of elements. Comparators can be passed to a sort method (such as
15: * <tt>cern.colt.Sorting.quickSort</tt>) to allow precise control over the sort order.<p>
16: *
17: * Note: It is generally a good idea for comparators to implement
18: * <tt>java.io.Serializable</tt>, as they may be used as ordering methods in
19: * serializable data structures. In
20: * order for the data structure to serialize successfully, the comparator (if
21: * provided) must implement <tt>Serializable</tt>.<p>
22: *
23: * @author wolfgang.hoschek@cern.ch
24: * @version 0.1 01/09/99
25: * @see java.util.Comparator
26: * @see cern.colt.Sorting
27: */
28: public interface IntComparator {
29: /**
30: * Compares its two arguments for order. Returns a negative integer,
31: * zero, or a positive integer as the first argument is less than, equal
32: * to, or greater than the second.<p>
33: *
34: * The implementor must ensure that <tt>sgn(compare(x, y)) ==
35: * -sgn(compare(y, x))</tt> for all <tt>x</tt> and <tt>y</tt>. (This
36: * implies that <tt>compare(x, y)</tt> must throw an exception if and only
37: * if <tt>compare(y, x)</tt> throws an exception.)<p>
38: *
39: * The implementor must also ensure that the relation is transitive:
40: * <tt>((compare(x, y)>0) && (compare(y, z)>0))</tt> implies
41: * <tt>compare(x, z)>0</tt>.<p>
42: *
43: * Finally, the implementer must ensure that <tt>compare(x, y)==0</tt>
44: * implies that <tt>sgn(compare(x, z))==sgn(compare(y, z))</tt> for all
45: * <tt>z</tt>.<p>
46: *
47: *
48: * @return a negative integer, zero, or a positive integer as the
49: * first argument is less than, equal to, or greater than the
50: * second.
51: */
52: int compare(int o1, int o2);
53:
54: /**
55: *
56: * Indicates whether some other object is "equal to" this
57: * Comparator. This method must obey the general contract of
58: * <tt>Object.equals(Object)</tt>. Additionally, this method can return
59: * <tt>true</tt> <i>only</i> if the specified Object is also a comparator
60: * and it imposes the same ordering as this comparator. Thus,
61: * <code>comp1.equals(comp2)</code> implies that <tt>sgn(comp1.compare(o1,
62: * o2))==sgn(comp2.compare(o1, o2))</tt> for every element
63: * <tt>o1</tt> and <tt>o2</tt>.<p>
64: *
65: * Note that it is <i>always</i> safe <i>not</i> to override
66: * <tt>Object.equals(Object)</tt>. However, overriding this method may,
67: * in some cases, improve performance by allowing programs to determine
68: * that two distinct Comparators impose the same order.
69: *
70: * @param obj the reference object with which to compare.
71: * @return <code>true</code> only if the specified object is also
72: * a comparator and it imposes the same ordering as this
73: * comparator.
74: * @see java.lang.Object#equals(java.lang.Object)
75: * @see java.lang.Object#hashCode()
76: */
77: boolean equals(Object obj);
78: }
|