de.caff.generics.function

## Interface DoubleOrdering

- All Superinterfaces:
    FloatOrdering
  All Known Subinterfaces:
    DoubleOrdering.Serial
  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 DoubleOrdering
      extends FloatOrdering

  Define an order for two primitive double values.

  Compared to a `Comparator<Double>` or `Ordering<Double>` this interface allows to avoid boxing and unboxing in various situations.

  Since:
    January 11, 2023
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `DoubleOrdering.Serial` A double ordering which is serializable.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static DoubleOrdering` | `NATURAL_ASCENDING` Natural order of ascending `double` values.
    `static DoubleOrdering` | `NATURAL_DESCENDING` Natural order of descending `double` values.
    `static DoubleOrdering` | `STANDARD_ASCENDING` Standard Java order of ascending `double` values.
    `static DoubleOrdering` | `STANDARD_DESCENDING` Inverse standard Java order of `double` values.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default boolean` | `ascending(double v1, double v2)` Are the two values represented in strictly ascending order?
    `default boolean` | `ascendingOrSame(double v1, double v2)` Are the two values represented in ascending order?
    `default java.util.Comparator<java.lang.Double>` | `asDoubleComparator()` Use this ordering as a comparator.
    `default Ordering<java.lang.Double>` | `asDoubleOrdering()` Get this ordering as a generic double ordering.
    `default java.util.Comparator<java.lang.Number>` | `asNumberComparator()` View this ordering as a number comparator.
    `default Ordering<java.lang.Number>` | `asNumberOrdering()` See this ordering as one working on general numbers.
    `Order` | `checkDouble(double v1, double v2)` Get the order of the two values.
    `default Order` | `checkFloat(float v1, float v2)` Get the order of the two values.
    `default boolean` | `descending(double v1, double v2)` Are the two values represented in strictly descending order?
    `default boolean` | `descendingOrSame(double v1, double v2)` Are the two values represented in descending order?
    `default boolean` | `different(double v1, double v2)` Are the two values considered different by this order?
    `static DoubleOrdering` | `fromComparator(java.util.Comparator<java.lang.Double> comparator)` Convert a standard comparator of `Double` into a double ordering.
    `default DoubleOrdering` | `inverse()` Invert this order.
    `default boolean` | `same(double v1, double v2)` Are the two values considered equal by this order?

    - ### Methods inherited from interface de.caff.generics.function.FloatOrdering

      `ascending, ascendingOrSame, asFloatComparator, asFloatOrdering, descending, descendingOrSame, different, fromComparator, same`

- - ### Field Detail

    - #### NATURAL_ASCENDING

          static final DoubleOrdering NATURAL_ASCENDING

      Natural order of ascending `double` values. Besides collapsing all NaN values and ordering them between everything else this ordering is nearer to IEEE 784 than standard `Double.compare(double, double)`.
      See Also:
        `Primitives.order(double, double)`, `STANDARD_ASCENDING`

    - #### NATURAL_DESCENDING

          static final DoubleOrdering NATURAL_DESCENDING

      Natural order of descending `double` values. Besides collapsing all NaN values and ordering them before everything else this ordering is nearer to IEEE 784 than standard `Double.compare(double, double)`.
      See Also:
        `Primitives.order(double, double)`, `STANDARD_DESCENDING`

    - #### STANDARD_ASCENDING

          static final DoubleOrdering STANDARD_ASCENDING

      Standard Java order of ascending `double` values. Please note that this order is broken as it considers `-0.0 < 0.0` which is not correct, for primitive `double` values `-0.0 == 0.0` is valid.
      See Also:
        `NATURAL_ASCENDING`

    - #### STANDARD_DESCENDING

          static final DoubleOrdering STANDARD_DESCENDING

      Inverse standard Java order of `double` values. Please note that this order is broken as it considers `-0.0 < 0.0` which is not correct, for primitive `double` values `-0.0 == 0.0` is valid.

  - ### Method Detail

    - #### checkDouble

          @NotNull
          Order checkDouble(double v1,
                                     double v2)

      Get the order of the two values.
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        order of the two values

    - #### checkFloat

          @NotNull
          default Order checkFloat(float v1,
                                            float v2)

      Description copied from interface: `FloatOrdering`
      Get the order of the two values.
      Specified by:
        `checkFloat` in interface `FloatOrdering`
      Parameters:
        `v1` - first value
        `v2` - second value
      Returns:
        order of the two values

    - #### asNumberOrdering

          @NotNull
          default Ordering<java.lang.Number> asNumberOrdering()

      See this ordering as one working on general numbers.
      Returns:
        this ordering but working on any number

    - #### ascending

          default boolean ascending(double v1,
                                    double 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(double, double)`, `ascendingOrSame(double, double)`, `descendingOrSame(double, double)`, `same(double, double)`, `different(double, double)`

    - #### ascendingOrSame

          default boolean ascendingOrSame(double v1,
                                          double 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(double, double)`, `descending(double, double)`, `descendingOrSame(double, double)`, `same(double, double)`, `different(double, double)`

    - #### descending

          default boolean descending(double v1,
                                     double 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(double, double)`, `ascendingOrSame(double, double)`, `descendingOrSame(double, double)`, `same(double, double)`, `different(double, double)`

    - #### descendingOrSame

          default boolean descendingOrSame(double v1,
                                           double 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(double, double)`, `descending(double, double)`, `ascendingOrSame(double, double)`, `same(double, double)`, `different(double, double)`

    - #### same

          default boolean same(double v1,
                               double 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(double, double)`, `descending(double, double)`, `ascendingOrSame(double, double)`, `descendingOrSame(double, double)`, `different(double, double)`

    - #### different

          default boolean different(double v1,
                                    double 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(double, double)`, `descending(double, double)`, `ascendingOrSame(double, double)`, `descendingOrSame(double, double)`, `same(double, double)`

    - #### inverse

          @NotNull
          default DoubleOrdering inverse()

      Invert this order.
      Specified by:
        `inverse` in interface `FloatOrdering`
      Returns:
        inverse order

    - #### asDoubleComparator

          @NotNull
          default java.util.Comparator<java.lang.Double> asDoubleComparator()

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

    - #### asNumberComparator

          @NotNull
          default java.util.Comparator<java.lang.Number> asNumberComparator()

      View this ordering as a number comparator.
      Specified by:
        `asNumberComparator` in interface `FloatOrdering`
      Returns:
        comparator of `Number`

    - #### asDoubleOrdering

          @NotNull
          default Ordering<java.lang.Double> asDoubleOrdering()

      Get this ordering as a generic double ordering.
      Returns:
        generic ordering for doubles

    - #### fromComparator

          @NotNull
          static DoubleOrdering fromComparator(@NotNull
                                                        java.util.Comparator<java.lang.Double> comparator)

      Convert a standard comparator of `Double` into a double ordering.
      Parameters:
        `comparator` - comparator of `Double`
      Returns:
        ordering