try to fix some minor dropdown bugs
[potlatch2.git] / org / idmedia / as3commons / util / Comparator.as
1 /*
2  * Copyright the original author or authors.
3  * 
4  * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  * 
8  *      http://www.mozilla.org/MPL/MPL-1.1.html
9  * 
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 package org.idmedia.as3commons.util {
17   
18   /**
19    * A comparison function, which imposes a <i>total ordering</i> on some
20    * collection of objects.  Comparators can be passed to a sort method (such as
21    * <tt>Collections.sort</tt>) to allow precise control over the sort order.
22    *
23    * @author sleistner
24    * @see Comparable
25    * @see Arrays#sort(Array, Comparator)
26    */
27   public interface Comparator {
28     
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)&gt;0) &amp;&amp; (compare(y, z)&gt;0))</tt> implies
41      * <tt>compare(x, z)&gt;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      * It is generally the case, but <i>not</i> strictly required that 
48      * <tt>(compare(x, y)==0) == (x.equals(y))</tt>.  Generally speaking,
49      * any comparator that violates this condition should clearly indicate
50      * this fact.  The recommended language is "Note: this comparator
51      * imposes orderings that are inconsistent with equals."
52      * 
53      * @param o1 the first object to be compared.
54      * @param o2 the second object to be compared.
55      * @return a negative integer, zero, or a positive integer as the
56      *         first argument is less than, equal to, or greater than the
57      *         second. 
58      */
59     function compare(o1:*, o2:*):int;
60     
61     /**
62      * 
63      * Indicates whether some other object is &quot;equal to&quot; this
64      * Comparator.  This method must obey the general contract of
65      * <tt>Object.equals(Object)</tt>.  Additionally, this method can return
66      * <tt>true</tt> <i>only</i> if the specified Object is also a comparator
67      * and it imposes the same ordering as this comparator.  Thus,
68      * <code>comp1.equals(comp2)</code> implies that <tt>sgn(comp1.compare(o1,
69      * o2))==sgn(comp2.compare(o1, o2))</tt> for every object reference
70      * <tt>o1</tt> and <tt>o2</tt>.<p>
71      *
72      * Note that it is <i>always</i> safe <i>not</i> to override
73      * <tt>Object.equals(Object)</tt>.  However, overriding this method may,
74      * in some cases, improve performance by allowing programs to determine
75      * that two distinct Comparators impose the same order.
76      *
77      * @param   obj   the reference object with which to compare.
78      * @return  <code>true</code> only if the specified object is also
79      *          a comparator and it imposes the same ordering as this
80      *          comparator.
81      */
82     function equals(obj:*):Boolean;
83   }
84 }