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 Comparators 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

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