| // Copyright (c) 2011, the Dart project authors. Please see the AUTHORS file |
| // for details. All rights reserved. Use of this source code is governed by a |
| // BSD-style license that can be found in the LICENSE file. |
| |
| part of dart.core; |
| |
| /** |
| * The signature of a generic comparison function. |
| * |
| * A comparison function represents an ordering on a type of objects. |
| * A total ordering on a type means that for two values, either they |
| * are equal or one is greater than the other (and the latter must then be |
| * smaller than the former). |
| * |
| * A [Comparator] function represents such a total ordering by returning |
| * |
| * * a negative integer if [a] is smaller than [b], |
| * * zero if [a] is equal to [b], and |
| * * a positive integer if [a] is greater than [b]. |
| */ |
| typedef int Comparator<T>(T a, T b); |
| |
| /** |
| * Interface used by types that have an intrinsic ordering. |
| * |
| * The [compareTo] operation defines a total ordering of objects, |
| * which can be used for ordering and sorting. |
| * |
| * The [Comparable] interface should be used for the natural ordering of a type. |
| * If a type can be ordered in more than one way, |
| * and none of them is the obvious natural ordering, |
| * then it might be better not to use the [Comparable] interface, |
| * and to provide separate [Comparator]s instead. |
| * |
| * It is recommended that the order of a [Comparable] agrees |
| * with its operator [operator ==] equality (`a.compareTo(b) == 0` iff `a == b`), |
| * but this is not a requirement. |
| * For example, [double] and [DateTime] have `compareTo` methods |
| * that do not agree with operator [operator ==]. |
| * For doubles the [compareTo] method is more precise than the equality, |
| * and for [DateTime] it is less precise. |
| * |
| * Examples: |
| * |
| * (0.0).compareTo(-0.0); // => 1 |
| * 0.0 == -0.0; // => true |
| * var dt = new DateTime.now(); |
| * var dt2 = dt.toUtc(); |
| * dt == dt2; // => false |
| * dt.compareTo(dt2); // => 0 |
| * |
| * The [Comparable] interface does not imply the existence |
| * of the comparison operators `<`, `<=`, `>` and `>=`. |
| * These should only be defined |
| * if the ordering is a less-than/greater-than ordering, |
| * that is, an ordering where you would naturally |
| * use the words "less than" about the order of two elements. |
| * |
| * If the equality operator and [compareTo] disagree, |
| * the comparison operators should follow the equality operator, |
| * and will likely also disagree with [compareTo]. |
| * Otherwise they should match the [compareTo] method, |
| * so that `a < b` iff `a.compareTo(b) < 0`. |
| * |
| * The [double] class defines comparison operators |
| * that are compatible with equality. |
| * The operators differ from `double.compareTo` on -0.0 and NaN. |
| * |
| * The [DateTime] class has no comparison operators, instead it has the more |
| * precisely named [DateTime.isBefore] and [DateTime.isAfter]. |
| */ |
| abstract class Comparable<T> { |
| /** |
| * Compares this object to another [Comparable] |
| * |
| * Returns a value like a [Comparator] when comparing `this` to [other]. |
| * That is, it returns a negative integer if `this` is ordered before [other], |
| * a positive integer if `this` is ordered after [other], |
| * and zero if `this` and [other] are ordered together. |
| * |
| * The [other] argument must be a value that is comparable to this object. |
| */ |
| int compareTo(T other); |
| |
| /** |
| * A [Comparator] that compares one comparable to another. |
| * |
| * It returns the result of `a.compareTo(b)`. |
| * |
| * This utility function is used as the default comparator |
| * for ordering collections, for example in the [List] sort function. |
| */ |
| static int compare(Comparable a, Comparable b) => a.compareTo(b); |
| } |