de.caff.generics.function

## Interface Ordering<T>

- All Known Subinterfaces:
    Ordering.Serial<E>
  Functional Interface:
    This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

      @FunctionalInterface
      public interface Ordering<T>

  Define an order for two objects of a generic type. An ordering always has to provide the following invariant: `order.compare(a, b) == order.compare(b, a).inverse()` for any two values of `a` and `b`. Note that this also implies `order.compare(a,a) == Order.Same` as `Order.Same` is the only result which is its own inverse.

  Ordering is very much the same as a `Comparator`, it just has a nicer result. Of course method `asComparator()` converts an ordering into a `Comparator`, and static factory method `fromComparator(Comparator)` does the inverse. It is recommended that `Comparator`s are serializable for usage with `TreeMap` and similar, and so this is true for orderings. See Ordering.Serial to get a general example.

  Since:
    January 11, 2023
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Ordering.Serial<E>` An ordering which is serializable.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default <S extends java.lang.Comparable<? super S>> Ordering<T>` | `andIfSame(java.util.function.Function<? super T,? extends S> keyExtractor)`
    `default <S> Ordering<T>` | `andIfSame(java.util.function.Function<? super T,? extends S> keyExtractor, Ordering<? super S> keyOrdering)`
    `default Ordering<T>` | `andIfSame(Ordering<? super T> lowerOrder)` Combine this ordering with a lower-level ordering.
    `default boolean` | `ascending(T v1, T v2)` Are the two values represented in strictly ascending order?
    `default boolean` | `ascendingOrSame(T v1, T v2)` Are the two values represented in ascending order?
    `default java.util.Comparator<T>` | `asComparator()` Use this ordering as a comparator.
    `default java.util.function.BiPredicate<T,T>` | `asEqualityChecker()` Use this ordering as a checker for equality.
    `Order` | `check(T v1, T v2)` Check the ordering of the two values.
    `default boolean` | `descending(T v1, T v2)` Are the two values represented in strictly descending order?
    `default boolean` | `descendingOrSame(T v1, T v2)` Are the two values represented in descending order?
    `default boolean` | `different(T v1, T v2)` Are the two values considered different by this order?
    `static <E> Ordering<E>` | `fromComparator(java.util.Comparator<E> comparator)` Convert a standard comparator of `Double` into a double ordering.
    `default Ordering<T>` | `inverse()` Invert this order.
    `static <E extends java.lang.Comparable<? super E>> Ordering<E>` | `inverseNatural()` Get the inverse of the natural order of a comparable type.
    `static <E extends java.lang.Comparable<? super E>> Ordering<E>` | `natural()` Get the natural order of a comparable type.
    `default Ordering<T>` | `nullsFirst()` Make this ordering null-safe in handling `null` values as coming before all other values.
    `default Ordering<T>` | `nullsLast()` Make this ordering null-safe in handling `null` values as coming after all other values.
    `static <S,K extends java.lang.Comparable<? super K>> Ordering<S>` | `ordering(java.util.function.Function<? super S,? extends K> keyExtractor)`
    `static <S,K> Ordering<S>` | `ordering(java.util.function.Function<? super S,? extends K> keyExtractor, Ordering<? super K> keyOrdering)`
    `static <S> Ordering<S>` | `orderingDouble(java.util.function.ToDoubleFunction<? super S> valueExtractor)`
    `static <S> Ordering<S>` | `orderingDouble(java.util.function.ToDoubleFunction<? super S> valueExtractor, DoubleOrdering ordering)`
    `default boolean` | `same(T v1, T v2)` Are the two values considered equal by this order?

- - ### Method Detail

    - #### check

          @NotNull
          Order check(T v1,
                               T v2)

      Check the ordering of the two values. This method has to fulfill the
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        order of the two values

    - #### ascending

          default boolean ascending(T v1,
                                    T v2)

      Are the two values represented in strictly ascending order?
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        `true` if `v1 < v2` according to this ordering
        `false` if `v1 >= v2` according to this ordering
      See Also:
        `descending(Object, Object)`, `ascendingOrSame(Object, Object)`, `descendingOrSame(Object, Object)`, `same(Object, Object)`, `different(Object, Object)`

    - #### ascendingOrSame

          default boolean ascendingOrSame(T v1,
                                          T v2)

      Are the two values represented in ascending order?
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        `true` if `v1 <= v2` according to this ordering
        `false` if `v1 > v2` according to this ordering
      See Also:
        `ascending(Object, Object)`, `descending(Object, Object)`, `descendingOrSame(Object, Object)`, `same(Object, Object)`, `different(Object, Object)`

    - #### descending

          default boolean descending(T v1,
                                     T v2)

      Are the two values represented in strictly descending order?
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        `true` if `v1 > v2` according to this ordering
        `false` if `v1 <= v2` according to this ordering
      See Also:
        `ascending(Object, Object)`, `ascendingOrSame(Object, Object)`, `descendingOrSame(Object, Object)`, `same(Object, Object)`, `different(Object, Object)`

    - #### descendingOrSame

          default boolean descendingOrSame(T v1,
                                           T v2)

      Are the two values represented in descending order?
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        `true` if `v1 >= v2` according to this ordering
        `false` if `v1 < v2` according to this ordering
      See Also:
        `ascending(Object, Object)`, `descending(Object, Object)`, `ascendingOrSame(Object, Object)`, `same(Object, Object)`, `different(Object, Object)`

    - #### same

          default boolean same(T v1,
                               T v2)

      Are the two values considered equal by this order?
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        `true` if `v1 == v2` according to this order
        `false` if `v1 != v2` according to this ordering
      See Also:
        `ascending(Object, Object)`, `descending(Object, Object)`, `ascendingOrSame(Object, Object)`, `descendingOrSame(Object, Object)`, `different(Object, Object)`

    - #### different

          default boolean different(T v1,
                                    T v2)

      Are the two values considered different by this order?
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        `true` if `v1 != v2` according to this order
        `false` if `v1 == v2` according to this ordering
      See Also:
        `ascending(Object, Object)`, `descending(Object, Object)`, `ascendingOrSame(Object, Object)`, `descendingOrSame(Object, Object)`, `same(Object, Object)`

    - #### inverse

          @NotNull
          default Ordering<T> inverse()

      Invert this order.
      Returns:
        inverse order

    - #### nullsFirst

          default Ordering<T> nullsFirst()

      Make this ordering null-safe in handling `null` values as coming before all other values.
      Returns:
        ordering sorting `null` values first

    - #### nullsLast

          default Ordering<T> nullsLast()

      Make this ordering null-safe in handling `null` values as coming after all other values.
      Returns:
        ordering sorting `null` values last

    - #### asComparator

          @NotNull
          default java.util.Comparator<T> asComparator()

      Use this ordering as a comparator.
      Returns:
        comparator of `Double`

    - #### andIfSame

          @NotNull
          default Ordering<T> andIfSame(@NotNull
                                                 Ordering<? super T> lowerOrder)

      Combine this ordering with a lower-level ordering. This lower level ordering will only take place if this ordering cannot differ between values and considers them to be `equal`.
      Parameters:
        `lowerOrder` - lower order
      Returns:
        combined order

    - #### andIfSame

          @NotNull
          default <S> Ordering<T> andIfSame(@NotNull
                                                     java.util.function.Function<? super T,? extends S> keyExtractor,
                                                     @NotNull
                                                     Ordering<? super S> keyOrdering)

    - #### andIfSame

          @NotNull
          default <S extends java.lang.Comparable<? super S>> Ordering<T> andIfSame(@NotNull
                                                                                             java.util.function.Function<? super T,? extends S> keyExtractor)

    - #### ordering

          @NotNull
          static <S,K> Ordering<S> ordering(@NotNull
                                                     java.util.function.Function<? super S,? extends K> keyExtractor,
                                                     @NotNull
                                                     Ordering<? super K> keyOrdering)

    - #### ordering

          @NotNull
          static <S,K extends java.lang.Comparable<? super K>> Ordering<S> ordering(@NotNull
                                                                                             java.util.function.Function<? super S,? extends K> keyExtractor)

    - #### orderingDouble

          @NotNull
          static <S> Ordering<S> orderingDouble(@NotNull
                                                         java.util.function.ToDoubleFunction<? super S> valueExtractor,
                                                         @NotNull
                                                         DoubleOrdering ordering)

    - #### orderingDouble

          @NotNull
          static <S> Ordering<S> orderingDouble(@NotNull
                                                         java.util.function.ToDoubleFunction<? super S> valueExtractor)

    - #### asEqualityChecker

          @NotNull
          default java.util.function.BiPredicate<T,T> asEqualityChecker()

      Use this ordering as a checker for equality.
      Returns:
        equality checker

    - #### fromComparator

          @NotNull
          static <E> Ordering<E> fromComparator(@NotNull
                                                         java.util.Comparator<E> comparator)

      Convert a standard comparator of `Double` into a double ordering.
      Type Parameters:
        `E` - type on which the order is defined
      Parameters:
        `comparator` - comparator of `Double`
      Returns:
        ordering

    - #### natural

          @NotNull
          static <E extends java.lang.Comparable<? super E>> Ordering<E> natural()

      Get the natural order of a comparable type.
      Type Parameters:
        `E` - comparable type
      Returns:
        natural order of the given comparable type

    - #### inverseNatural

          @NotNull
          static <E extends java.lang.Comparable<? super E>> Ordering<E> inverseNatural()

      Get the inverse of the natural order of a comparable type.
      Type Parameters:
        `E` - comparable type
      Returns:
        inverse natural order of the given comparable type