# HG changeset patch
# User igerasim
# Date 1503988648 25200
# Mon Aug 28 23:37:28 2017 -0700
# Node ID 62137618d00310efaa3545ced9fa2d2cade487d8
# Parent ebdaa1e7ab33aa87921e32bc3a5f55834da49872
[mq]: 8134512-provide-Alpha-Numeric-logical-Comparator
diff --git a/src/java.base/share/classes/java/util/Comparator.java b/src/java.base/share/classes/java/util/Comparator.java
--- a/src/java.base/share/classes/java/util/Comparator.java
+++ b/src/java.base/share/classes/java/util/Comparator.java
@@ -30,7 +30,6 @@
import java.util.function.ToIntFunction;
import java.util.function.ToLongFunction;
import java.util.function.ToDoubleFunction;
-import java.util.Comparators;
/**
* A comparison function, which imposes a total ordering on some
@@ -526,9 +525,162 @@
* @throws NullPointerException if the argument is null
* @since 1.8
*/
- public static Comparator comparingDouble(ToDoubleFunction super T> keyExtractor) {
+ public static Comparator comparingDouble(ToDoubleFunction super T> keyExtractor) {
Objects.requireNonNull(keyExtractor);
return (Comparator & Serializable)
(c1, c2) -> Double.compare(keyExtractor.applyAsDouble(c1), keyExtractor.applyAsDouble(c2));
}
+
+ /**
+ * The returned comparator compares two character sequences as though each
+ * of them would be first transformed into a tuple of the form:
+ *
{@code (A0, N0, A1, N1, ..., An-1, Nn-1, An, Nn)}
+ * where:
+ *
{@code A0} and {@code An} are (possibly empty) sub-sequences
+ * consisting of non-decimal-digit characters,
+ *
{@code A1 ... An-1} are non-empty sub-sequences consisting of
+ * non-decimal-digit characters,
+ *
{@code N0 ... Nn-1} are non-empty sub-sequences consisting of
+ * decimal-digit characters, and
+ *
{@code Nn} is a (possibly empty) sub-sequence consisting of
+ * decimal-digit characters.
+ *
+ *
All sub-sequences concatenated together in order as they appear in the
+ * tuple yield the original character sequence.
+ *
+ * After transformation, the tuples are compared by their elements (from
+ * left to right) so that corresponding {@code Ax} elements are compared
+ * using the provided comparator {@code alphaComparator} and {@code Nx}
+ * elements are compared as non negative decimal integers.
+ *
+ * The first pair of compared elements that is different with respect to the
+ * used comparator (either {@code alphaComparator}, or special decimal
+ * comparator) if any, provides the result produced by this comparator.
+ * The arguments are treated equal, if and only if all the subsequences,
+ * both decimal and non-decimal, compare equal.
+ *
+ *
For example, the following array was sorted using such comparator:
+ *
When comparing numerical parts, an empty character sequence is
+ * considered less than any non-empty sequence of decimal digits.
+ *
+ *
If the numeric values of two compared character sub-sequences are
+ * equal, but their string representations have different number of leading
+ * zeroes, the comparator treats the number with less leading zeros as
+ * smaller.
+ * For example, {@code "abc 1" < "abc 01" < "abc 001"}.
+ *
+ * @apiNote For example, to sort a collection of {@code String} based on
+ * case-insensitive ordering, and treating numbers with more leading
+ * zeroes as greater, one could use
+ *
+ *
+ *
+ * @implSpec To test if the given code point represents a decimal digit,
+ * the comparator checks if {@link java.lang.Character#getType(int)}
+ * returns value {@link java.lang.Character#DECIMAL_DIGIT_NUMBER}.
+ * The comparator uses {@link java.lang.Character#digit(int, int)} with
+ * the second argument set to {@code 10} to determine the numeric
+ * value of a digit represented by the given code point.
+ *
+ * @param alphaComparator the comparator that compares sub-sequences
+ * consisting of non-decimal-digits
+ * @param the type of elements to be compared; normally
+ * {@link java.lang.CharSequence}
+ * @return a comparator that compares character sequences, following the
+ * rules described above
+ * @throws NullPointerException if the argument is null
+ *
+ * @since 10
+ */
+ public static Comparator
+ comparingAlphaDecimal(Comparator super CharSequence> alphaComparator) {
+ return new Comparators.AlphaDecimalComparator<>(
+ Objects.requireNonNull(alphaComparator), false);
+ }
+
+ /**
+ * The returned comparator compares two character sequences as though each
+ * of them would be first transformed into a tuple of the form:
+ *
{@code (A0, N0, A1, N1, ..., An-1, Nn-1, An, Nn)}
+ * where:
+ *
{@code A0} and {@code An} are (possibly empty) sub-sequences
+ * consisting of non-decimal-digit characters,
+ *
{@code A1 ... An-1} are non-empty sub-sequences consisting of
+ * non-decimal-digit characters,
+ *
{@code N0 ... Nn-1} are non-empty sub-sequences consisting of
+ * decimal-digit characters, and
+ *
{@code Nn} is a (possibly empty) sub-sequence consisting of
+ * decimal-digit characters.
+ *
+ *
All sub-sequences concatenated together in order as they appear in the
+ * tuple yield the original character sequence.
+ *
+ * After transformation, the tuples are compared by their elements (from
+ * left to right) so that corresponding {@code Ax} elements are compared
+ * using the provided comparator {@code alphaComparator} and {@code Nx}
+ * elements are compared as non negative decimal integers.
+ *
+ * The first pair of compared elements that is different with respect to the
+ * used comparator (either {@code alphaComparator}, or special decimal
+ * comparator) if any, provides the result produced by this comparator.
+ * The arguments are treated equal, if and only if all the subsequences,
+ * both decimal and non-decimal, compare equal.
+ *
+ *
For example, the following array was sorted using such comparator:
+ *
When comparing numerical parts, an empty character sequence is
+ * considered less than any non-empty sequence of decimal digits.
+ *
+ *
If the numeric values of two compared character sub-sequences are
+ * equal, but their string representations have different number of leading
+ * zeroes, the comparator treats the number with more leading zeros as
+ * smaller.
+ * For example, {@code "abc 001" < "abc 01" < "abc 1"}.
+ *
+ * @apiNote For example, to sort a collection of {@code String} based on
+ * case-insensitive ordering, and treating numbers with less leading
+ * zeroes as greater, one could use
+ *
+ *